Messaging function and event reference
The StarknetMessaging smart contracts include functions and events that are required when sending messages between L1 and L2.
For information on the messaging mechanism, see Messaging mechanism.
The L1 functions, where available, are defined in the following smart contract:
| Contract | Description | Functions |
|---|---|---|
The contract that implements messaging functions. Interfaces are available through |
The L1 events, where available, are defined in the following smart contract:
| Contract | Description | Events |
|---|---|---|
The contract that defines messaging events. |
L1 function reference
Functions are listed in alphabetical order.
cancelL1ToL2Message
Description
Cancels an L1 to L2 message. Call this function after calling the startL1ToL2MessageCancellation function. The time between the calls to these two functions must be at least the number of seconds defined by the messageCancellationDelay function.
Only a sender can cancel a message.
If the message is missing, the call reverts.
Be aware that the message fee is not refunded.
State Mutability
None.
Parameters
uint256 toAddress
|
The address of the L2 contract. |
uint256 selector
|
The function, in the recipient L2 contract, that the message called. |
uint256[] calldata payload
|
The payload of the message. |
uint256 nonce
|
The nonce of the message. |
Returns
bytes32 msgHash
|
The hash of the canceled message. |
Emitted event
Function definition
Contract: StarknetMessaging.sol
-
Function:
cancelL1ToL2Message
consumeMessageFromL2
Description
Consumes a message that was sent from an L2 contract.
Returns the hash of the message.
State Mutability
None.
Parameters
uint256 fromAddress
|
The address of the L2 contract sending the message. |
uint256[] calldata payload
|
The payload of the message. |
Returns
bytes32 msgHash
|
The hash of the consumed message. |
Emitted event
Function definition
Contract: StarknetMessaging.sol
-
Function:
consumeMessageFromL2
getMaxL1MsgFee
Description
Returns the maximum fee, in Wei, that Starknet accepts for a single message. If the fee passed is higher than this value, the transaction is not accepted.
State Mutability
pure
Parameters
None.
Returns
uint256 MAX_L1_MSG_FEE
|
The maximum fee, in Wei, that Starknet accepts for a single message. |
Function definition
Contract: StarknetMessaging.sol
-
Function:
getMaxL1MsgFee
l1ToL2MessageCancellations
Description
Returns the timestamp of the cancellation request.
State Mutability
view
Parameters
bytes32 msgHash
|
The message hash. |
Returns
uint256 result
|
The Ethereum block timestamp. |
Returns 0 if cancelL1ToL2Message was not called with the message hash msgHash.
Function definition
Contract: StarknetMessaging.sol
-
Function:
l1ToL2MessageCancellations
l1ToL2MessageNonce
Description
Returns the nonce of the next message sent to the L2 contract. So if If n messages have been sent to Starknet, this function returns n + 1.
State Mutability
view
Parameters
None.
Returns
uint256 nonce
|
The nonce of the next message sending to L2 contract. |
Function definition
Contract: StarknetMessaging.sol
-
Function:
l1ToL2MessageNonce
l1ToL2Messages
Description
Indicates if a pending message is associated with a given message hash.
State Mutability
view
Parameters
bytes32 msgHash
|
The message hash. |
Returns
Returns uint256 result, where result is one of the following:
message_fee + 1
|
A pending message is associated with the |
0
|
No pending message is associated with the |
Function definition
Contract: StarknetMessaging.sol
-
Function:
l1ToL2Messages
l2ToL1Messages
Description
Indicates the number of pending messages associated with a given message hash.
State Mutability
view
Parameters
bytes32 msgHash
|
The message hash. |
Returns
Returns uint256 result, where result is the number of pending messages associated with the msgHash parameter.
Function definition
Contract: StarknetMessaging.sol
-
Function:
l2ToL1Messages
messageCancellationDelay
Description
Returns the time interval, in seconds, after which you can cancel a message starting from the moment of calling the startL1ToL2MessageCancellation function. You can get the real value by calling the messageCancellationDelay function on a block explorer, such as Etherscan.
State Mutability
view
Parameters
None.
Returns
uint256 result
|
The time interval. |
Function definition
Contract: StarknetMessaging.sol
-
Function:
messageCancellationDelay
sendMessageToL2
Description
Sends a message to an L2 contract. The message fee is the cost of executing this function.
State Mutability
payable
Parameters
uint256 toAddress
|
The address of the L2 contract. |
uint256 selector
|
The function, in the recipient L2 contract, that the message called. |
uint256[] calldata payload
|
The payload of the message. |
Returns
bytes32 msgHash
|
The hash of the message. |
uint256 nonce
|
The nonce of the message. |
Emitted event
Function definition
Contract: StarknetMessaging.sol
-
Function:
sendMessageToL2
startL1ToL2MessageCancellation
Description
Starts the cancellation of a message from L1 to L2.
You can cancel a message after a predefined about of time from the moment this function is called. The amount of time is set by the messageCancellationDelay function.
You can only call this function for a message that is currently pending, and the caller must be the sender of that message.
State Mutability
None.
Parameters
uint256 toAddress
|
The address of the L2 contract. |
uint256 selector
|
The function, in the recipient L2 contract, that the message called. |
uint256[] calldata payload
|
The payload of the message. |
uint256 nonce
|
The nonce of the message. |
Returns
bytes32 msgHash
|
The hash of the cancellation message. |
Emitted event
Function definition
Contract: StarknetMessaging.sol
-
Function:
startL1ToL2MessageCancellation
L1 event reference
Events are listed in alphabetical order.
ConsumedMessageToL1
Description
This event is emitted when a message from L2 to L1 is consumed by the consumeMessageFromL2 function.
Event attributes
uint256 indexed fromAddress
|
The address of the sender on L2. |
address indexed toAddress
|
The address of the receiver on L1. |
uint256[] payload
|
The payload of the consumed message. |
Event definition
-
Contract:
IStarknetMessagingEvents -
Event:
ConsumedMessageToL1
LogMessageToL2
Description
This event is emitted when a message is sent from L1 to L2 by the sendMessageToL2 function.
Event attributes
address indexed fromAddress
|
The address of the sender on L1. |
uint256 indexed toAddress
|
The address of the receiver on L2. |
uint256 indexed selector
|
The function, in the recipient L2 contract, that the message called. |
uint256[] payload
|
The payload of the message. |
uint256 nonce
|
The nonce of the message. |
uint256 fee
|
The fee associated with the message. |
Event definition
-
Contract:
IStarknetMessagingEvents -
Event:
LogMessageToL2
MessageToL2Canceled
Description
This event is emitted when an L1 to L2 message is canceled by the cancelL1ToL2Message function.
Event attributes
address indexed fromAddress
|
The address of the sender on L1. |
uint256 indexed toAddress
|
The address of the receiver on L2. |
uint256 indexed selector
|
The function, in the recipient L2 contract, that the message called. |
uint256[] payload
|
The payload of the canceled message. |
uint256 nonce
|
The nonce of the canceled message. |
Event definition
-
Contract:
IStarknetMessagingEvents -
Event:
MessageToL2Canceled
MessageToL2CancellationStarted
Description
This event is emitted when the cancellation of an L1 to L2 message is started by the startL1ToL2MessageCancellation function.
Event attributes
address indexed fromAddress
|
The address of the sender on L1. |
uint256 indexed toAddress
|
The address of the receiver on L2. |
uint256 indexed selector
|
The function, in the recipient L2 contract, that the message called. |
uint256[] payload
|
The payload of the message to be canceled. |
uint256 nonce
|
The nonce of the message to be canceled. |
Event definition
-
Contract:
IStarknetMessagingEvents