L1 to L2 messaging

In the Transaction Lifecycle section, we covered how users interact with child chain contracts. They submit transactions by putting messages into the chain’s inbox or having a full node Sequencer or aggregator do so on their behalf.

Parent and child chain chains run asynchronously from each other, so it is not possible to make a cross-chain call that produces a result within the same Transaction as the caller. Instead, cross-chain calls must be asynchronous, meaning that the caller submits the call at some point in time, and the call runs later. Consequently, a cross-chain contract-to-contract call can never produce a result available to the calling contract (except for acknowledgment of a successful call submitted for later execution).

In this section, we will discuss how contracts interact between parent chain and child chain, how a parent chain contract is called a child chain contract, and vice versa.

Retryable Tickets

Retryable tickets are Arbitrum's canonical method for creating parent to child chain messages, i.e., parent chain transactions that initiate a message to be executed on child chain. A retryable can be submitted for a fixed cost (dependent only on its calldata size) paid at the parent chain; its submission on the parent chain is separable / asynchronous with its execution on the child chain. Retryables provide atomicity between the cross chain operations; if the parent chain transaction to request submission succeeds (i.e., does not revert) then the execution of the Retryable on the child chain has a strong guarantee to ultimately succeed as well.

Retryable Tickets Lifecycle

Here we walk through the different stages of the lifecycle of a Retryable Ticket; (1) submission, (2) auto-redemption, and (3) manual redemption.

Submission

1. Creating a retryable ticket is initiated with a call (direct or internal) to the createRetryableTicket function of the inbox contract. A ticket is guaranteed to be created if this call succeeds. Here, we describe parameters that need to be carefully set. Note that, this function forces the sender to provide a reasonable amount of funds (at least enough to submitting, and attempting to executing the ticket), but that doesn't guarantee a successful auto-redemption.

Parameter	Description
l1CallValue (also referred to as deposit)	Not a real function parameter, it is rather the callValue that is sent along with the transaction
address to	The destination child chain address
uint256 l2CallValue	The callvalue for retryable child chain message that is supplied within the deposit (l1CallValue)
uint256 maxSubmissionCost	The maximum amount of ETH to be paid for submitting the ticket. This amount is (1) supplied within the deposit (l1CallValue) to be later deducted from sender's child chain balance and is (2) directly proportional to the size of the retryable’s data and the parent chain basefee
address excessFeeRefundAddress	The unused gas cost and submssion cost will deposit to this address, formula is: (gasLimit x maxFeePerGas - execution cost) + (maxSubmission - (autoredeem ? 0 : submission cost)). (Note: excess deposit will transfer to the alias address of the Parent chain tx's msg.sender rather than this address)
address callValueRefundAddress	The child chain address to which the l2CallValue is credited if the ticket times out or gets cancelled (this is also called the beneficiary, who's got a critical permission to cancel the ticket)
uint256 gasLimit	Maximum amount of gas used to cover the child chain execution of the ticket
uint256 maxFeePerGas	The gas price bid for the child chain execution of the ticket that is supplied within the deposit (l1CallValue)
bytes calldata data	The calldata to the destination child chain address

2. Sender's deposit must be enough to make the parent chain submission succeed and for the child chain execution to be attempted. If provided correctly, a new ticket with a unique TicketID is created and added to retryable buffer. Also, funds (submissionCost + l2CallValue) are deducted from the sender and placed into the escrow for later use in redeeming the ticket.

3. Ticket creation causes the ArbRetryableTx precompile to emit a TicketCreated event containing the TicketID on child chain.

Automatic Redemption

4. It is very important to note that the submission of a ticket on the parent chain is separable / asynchronous from its execution on child chain, i.e., a successful parent chain ticket creation does not guarantee a successful redemption. Once the ticket is successfully created, the two following conditions are checked: (1) if the user's child chain balance is greater than (or equal to) maxFeePerGas * gasLimit and (2) if the maxFeePerGas (provided by the user in the ticket submission process) is greater than (or equal to) the l2Basefee. If these conditions are both met, ticket's submission is followed by an attempt to execute it on child chain (i.e., an auto-redeem using the supplied gas, as if the redeem method of the ArbRetryableTx precompile had been called). Depending on how much gas the sender has provided in step 1, ticket's redemption can either (1) immediately succeed or (2) fail. We explain both situations here:

• If the ticket is successfully auto-redeemed, it will execute with the sender, destination, callvalue, and calldata of the original submission. The submission fee is refunded to the user on the child chain (excessFeeRefundAddress). Note that to ensure successful auto-redeem of the ticket, one could use the Arbitrum SDK which provides a convenience function that returns the desired gas parameters when sending L1-L2 messages.

• If a redeem is not done at submission or the submission's initial redeem fails (for example, because the child chain gas price has increased unexpectedly), the submission fee is collected on the child chain to cover the resources required to temporarily keep the ticket in memory for a fixed period (one week), and only in this case, a manual redemption of the ticket is required (see next section).

Manual Redemption

5. At this point, anyone can attempt to manually redeem the ticket again by calling ArbRetryableTx's redeem precompile method, which donates the call's gas to the next attempt. Note that the amount of gas is NOT limited by the original gasLimit set during the ticket creation. ArbOS will enqueue the redeem, which is its own special ArbitrumRetryTx type, to its list of redeems that ArbOS guarantees to exhaust before moving on to the next non-redeem transaction in the block its forming. In this manner redeems are scheduled to happen as soon as possible, and will always be in the same block as the tx that scheduled it. Note that the redeem attempt's gas comes from the call to redeem, so there's no chance the block's gas limit is reached before execution.

6. If the fixed period (one week) elapses without a successful redeem, the ticket expires and will be automatically discarded, unless some party has paid a fee to keep the ticket alive for another full period. A ticket can live indefinitely as long as it is renewed each time before it expires.

Avoid Losing Funds!

If a ticket expires after seven days without being redeemed or re-scheduled to a future date, any message and value (other than the escrowed callvalue) it carries could be lost without possibility of being recovered.

On success, the To address receives the escrowed callvalue, and any unused gas is returned to ArbOS's gas pools. On failure, the callvalue is returned to the escrow for the future redeem attempt. In either case, the network fee was paid during the scheduling tx, so no fees are charged and no refunds are made.

Note that during redemption of a ticket, attempts to cancel the same ticket, or to schedule another redeem of the same ticket, will revert. In this manner retryable tickets are not self-modifying.

If a ticket with a callvalue is eventually discarded (cancelled or expired), having never successfully run, the escrowed callvalue will be paid out to a callValueRefundAddress account that was specified in the initial submission Step 1.

Important Notes:

If a redeem is not done at submission or the submission's initial redeem fails, anyone can attempt to redeem the retryable again by calling ArbRetryableTx's redeem precompile method, which donates the call's gas to the next attempt. ArbOS will enqueue the redeem, which is its own special ArbitrumRetryTx type, to its list of redeems that ArbOS guarantees to exhaust before moving on to the next non-redeem transaction in the block its forming. In this manner redeems are scheduled to happen as soon as possible, and will always be in the same block as the transaction that scheduled it. Note that the redeem attempt's gas comes from the call to redeem, so there's no chance the block's gas limit is reached before execution.

• One can redeem live tickets using the Arbitrum Retryables Transaction Panel
• The calldata of a ticket is saved on the child chain until it is redeemed or expired
• Redeeming cost of a ticket will not increase over time, it only depends on the current gas price and gas required for execution

Receipts

In the lifecycle of a retryable ticket, two types of child chain transaction receipts will be emitted:

• Ticket Creation Receipt: This receipt indicates that a ticket was successfully created; any successful parent chain call to the Inbox's createRetryableTicket method is guaranteed to create a ticket. The ticket creation receipt includes a TicketCreated event (from ArbRetryableTx), which includes a ticketId field. This ticketId is computable via RLP encoding and hashing the transaction; see calculateSubmitRetryableId.
• Redeem Attempt: A redeem attempt receipt represents the result of an attempted child chain execution of a ticket, i.e, success / failure of that specific redeem attempt. It includes a RedeemScheduled event from ArbRetryableTx, with a ticketId field. At most, one successful redeem attempt can ever exist for a given ticket; if, e.g., the auto-redeem upon initial creation succeeds, only the receipt from the auto-redeem will ever get emitted for that ticket. If the auto-redeem fails (or was never attempted — i.e., the provided child gas limit * L2 gas price = 0), each initial attempt will emit a redeem attempt receipt until one succeeds.

Alternative "unsafe" Retryable Ticket Creation

The Inbox.createRetryableTicket convenience method includes sanity checks to help minimize the risk of user error: the method will ensure that enough funds are provided directly from the parent chain to cover the current cost of ticket creation. It also will convert the provided callValueRefundAddress and excessFeeRefundAddress to their Address Alias (see below) if either is a contract (determined by if the address has code during the call), providing a path for the parent chain contract to recover funds. A power-user may bypass these sanity-check measures via the Inbox's unsafeCreateRetryableTicket method; as the method's name desperately attempts to warn you, it should only be accessed by a user who truly knows what they're doing.

Eth deposits

A special message type exists for simple Eth deposits; i.e., sending Eth from the parent chain to child chain. Eth can be deposited via a call to the Inbox's depositEth method. If the parent chain caller is EOA, the Eth will be deposited to the same EOA address on child chain; the parent chain caller is a contract, the funds will deposited to the contract's aliased address (see below).

Note that depositing Eth via depositEth into a contract on the child chain will not trigger the contract's fallback function.

In principle, retryable tickets can alternatively be used to deposit Ether; this could be preferable to the special eth-deposit message type if, e.g., more flexibility for the destination address is needed, or if one wants to trigger the fallback function on the child chain side.

Transacting via the Delayed Inbox

While retryables and Eth deposits must be submitted through the Delayed Inbox, in principle, any message can be included this way; this is a necessary recourse to ensure the Arbitrum chain preserves censorship resistance even if the Sequencer misbehaves (see The Sequencer and Censorship Resistance). However, under ordinary/happy circumstances, the expectation/recommendation is that clients use the delayed inbox only for Retryables and Eth deposits, and transact via the Sequencer for all other messages.

Address Aliasing

Unsigned messages submitted via the Delayed Inbox get their sender's addressed "aliased": when these messages are executed on the child chain, the sender's address —i.e., that which is returned by msg.sender — will not simply be the parent chain address that sent the message; rather it will be the address's "L2 Alias." An address's L2 alias is its value increased by the hex value 0x1111000000000000000000000000000000001111:

L2_Alias = L1_Contract_Address + 0x1111000000000000000000000000000000001111

Try it out

The Arbitrum protocol's usage of child chain (L2) Aliases for Parent chain-to-child chain messages prevents cross-chain exploits that would otherwise be possible if we simply reused the same parent chain (L1) addresses as the child chain (L2) sender; i.e., tricking a child chain contract that expects a call from a given contract address by sending retryable ticket from the expected contract address on the parent chain.

If for some reason you need to compute the parent chain address from an child chain alias on chain, you can use our AddressAliasHelper library:

modifier onlyFromMyL1Contract() override {
    require(AddressAliasHelper.undoL1ToL2Alias(msg.sender) == myL1ContractAddress, "ONLY_COUNTERPART_CONTRACT");
    _;
}

Signed Messages

The delayed inbox can also accept messages that include a signature. In this case, the message will execute with the msg.sender address equal to the address that produced the included signature (i.e., not its alias). Intuitively, the signature proves that the sender address is not a contract, and thus is safe from cross-chain exploit concerns described above. Thus, it can safely execute from signer's address, similar to a transaction included in a Sequencer's Batch. For these messages, the address of the parent chain sender is effectively ignored at child chain.

These signed messages submitted through the delayed inbox can be used to execute messages that bypass the Sequencer and require EOA authorization at child chain, e.g., force-including an Ether withdrawal (see "withdraw eth tutorial").