CCIP Manual Execution (TON)

In general, messages are successfully delivered and processed via CCIP as described in the Architecture page. However, some exceptional conditions might require users to manually execute the transaction on the destination blockchain:

• The receiver contract on the destination blockchain reverted due to an unhandled exception such as a logical error.
• The receiver contract on the destination blockchain reverted due to the gas limit being insufficient to execute the triggered function (Note: The gas limit value is set in the extraArgs param of the message).

The flowchart below displays the process of a cross-chain transaction, detailing the steps involved in the manual execution:

CCIP execution

1. A sender contract or EOA initiates a CCIP message on the source blockchain.
2. CCIP Committing DON awaits finality on the source blockchain.
3. Post finality, the CCIP Committing DON assembles a batch of eligible transactions, computes a Merkle root, and records it to the OffRamp contract on the destination blockchain.
4. After the committed Merkle root is blessed, the CCIP Executing DON proceeds with the execution on the destination blockchain.
5. The execution on the destination blockchain works as follows: if the receiver execution fails due to gas limits or unhandled exceptions, the transaction becomes eligible for manual execution.

Manual execution

As described above, a CCIP message becomes eligible for manual execution for various reasons. Manual execution means that a user has to manually trigger the execution of the destination transaction after the issue that caused manual execution has been resolved.

When a CCIP message is eligible for manual execution, the CCIP explorer shows the following information:

• Ready for manual execution status
• The possibility to override the gas limit and a Trigger Manual Execution button

Depending on the situation, you can take one of the following steps:

• Insufficient gas limit: The executor can connect their wallet, override the gas limit parameter, increase the gas limit for this particular execution, and trigger a manual execution. If this new gas limit override is sufficient, the transaction will go through successfully. Note: This gas limit override applies only to this manually executed transaction.
• Unhandled exception (logical error) in the receiver contract: If the receiver contract is upgradeable, developers must correct the logic, re-deploy the logic contract, and then manually execute the same transaction. If the receiver contract is not upgradeable, developers must deploy a new receiver contract, and then users can send a new CCIP message. Non-upgradable contracts will not benefit from manual execution. Note: Always make sure to test your smart contracts thoroughly. As a best practice, implement fallback mechanisms in the CCIP receiver contracts to manage unhandled exceptions gracefully.

When manual execution is initiated, a Merkle proof is generated for the message to be executed. During execution, the CCIP explorer submits the Merkle proof and the new gas limit (if the initial failure was due to a low gas limit). This Merkle proof is verified by the OffRamp contract against the Merkle root in the OffRamp contract. This mirrors the automated execution performed by the CCIP Executing DON, with the addition that the execution is resubmitted using the gas limit you provide.

Frequently asked questions

1. Can anyone execute a transaction on the CCIP explorer even if they are not the initiator of the transaction?

   Yes, any EOA can manually execute a CCIP message that is eligible for manual execution. However, the executing account must have sufficient native gas tokens to cover the gas costs associated with the delivery of the CCIP message.

   
   

2. If a user sends multiple messages and the first message isn't successfully delivered and goes into a manual execution mode, does that mean all subsequent messages from the user will also be stuck?

   It depends. If a message goes into manual execution mode due to receiver errors (unhandled exceptions or gas limit issues), subsequent messages don't get automatically blocked, unless they would encounter the same error. However, suppose a message goes into manual execution mode after the Smart Execution time window expires (currently 8 hours). In that case, subsequent messages must wait for the first message to be processed to maintain the default sequence.

   
   

3. If the maximum gas limit is 3M (3,000,000) on mainnet, but it turns out that the destination blockchain requires more than that, will an override of > 3M still work?

   Yes, but only for this execution. This works because the gas limit for this execution instance isn't passing through the CCIP validation for the gas limit, for which the CCIP executing DON pays the gas. However, if you consistently need more than 3M for your use case, please reach out to us via this contact form.

   
   

4. Will Chainlink Labs reimburse us for manual execution fees?

   Since most manual execution situations are due to insufficient gas limit or an unhandled exception in the receiver contract, Chainlink Labs does not reimburse these fees. If you are a dApp developer, please ensure you test thoroughly to avoid manual executions to the extent possible.

   
   

5. Do I have to manually execute via the CCIP explorer? Are there any other ways to do this?

   The CCIP explorer provides the easiest way to execute manually. It handles all the complexity of submitting the Merkle proof needed for successful transaction execution. Alternatively, you can use CCIP Tools — either the CCIP SDK or the CCIP CLI — to trigger manual execution programmatically.

   
   

6. How do I know if my receiver error is due to a gas limit issue or an unhandled exception?

   If you see a ReceiverError with a revert reason as empty (0x), this is likely due to a gas limit issue. Determine the gas limit that would work for your transaction and manually override it.

   
   

7. How can I write contracts that avoid manual execution situations in the first place?

   • Test thoroughly to ensure logical conditions for all paths are gracefully handled in your receiver contract.
   • Set a gas limit that works for complex execution paths, not just the simplest ones. Read the best practices for TON-specific guidance.
     

8. My transaction meets one of the conditions to trigger manual execution, but I do not see this option on the CCIP explorer. How am I supposed to execute this manually?

   This should not happen, but in the unlikely scenario that it does, please submit a support ticket as shown below. Include the CCIP Message ID, your preferred contact details, and a detailed description of the issue you faced. This will help us assist you more effectively.