Sending modes

By default, message sending process has the following properties:

• the forward fees are paid from the indicated message value, so it is decreased by the amount of forward fees before sending;
• if sending fails, the transaction is rolled back and a bounce message is not sent.

The purpose of send modes is to modify the above logic by specifying:

• what exactly value should be in the outgoing message (will it be increased by something or even reset to some value);
• whether to pay forward fees from the account balance or from the message value;
• whether to rollback the transaction and send a bounce message if sending fails, etc.

The send modes are specified via an 8-bit bitmask mode parameter of the SENDRAWMSG or the SENDMSG instructions. The resulting mode value can have the following base modes:

Additionally, the resulting mode can have the following optional flags added:

Behavior

Notation:

• value – the amount of Toncoin indicated in the outgoing message.
• mode – the bitmask passed to the SENDRAWMSG or the SENDMSG instructions.
• msg_balance_remaining – the remaining value of the incoming message. At the start of the action phase it equals either the incoming message value or account's balance before compute phase if it was less than the value of incoming message with bounce flag set to false. At the start of sending message process, it is zero if there was the previous sending message action with modes SEND_MODE_CARRY_ALL_BALANCE or SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE, otherwise it equals the value described above.
• remaining_balance – the remaining balance of the account at the start of the action.
• fwd_fees – the amount of forward fees for sending the message.
• gas_fees – the fees paid for gas used during the computation phase.
• action_fine – the accumulated fine for the previous failed and skipped send message actions.
• final_value – the final value of the outgoing message.
• req – value that will be deducted from the account balance.

The algorithm for the resulting value of outgoing internal message and amount of nanotoncoins that will be deducted from account's balance is as follows:

1. Check that mode has flag SEND_MODE_BOUNCE_ON_ACTION_FAIL:
   • if so, then in case of any failure the action phase will be interrupted, the bounce phase will be initiated;
   • if not, then in case of any failure the action phase will be interrupted but no bounce message will be sent.
2. Check that mode has flag SEND_MODE_IGNORE_ERRORS:
   • if so, then in case of almost all failure (errors on which this mode is not work are described in Errors subsection.) during sending the message an error will be ignored and the action phase will continue;
3. Set final_value to the value.
4. Check that mode has base mode SEND_MODE_CARRY_ALL_BALANCE:
   • if so, then set final_value to remaining_balance and remove +1 flag from mode if it is presented.
5. Otherwise, check that mode has base mode SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE:
   1. Check that mode has flag SEND_MODE_PAY_FEES_SEPARATELY:
      • if so, then increase final_value by msg_balance_remaining;
      • otherwise, increase final_value by msg_balance_remaining - gas_fees - action_fine.
6. Set req to final_value.
7. Check that mode has flag SEND_MODE_PAY_FEES_SEPARATELY:
   • if so, then increase req by fwd_fees.
   • otherwise, decrease final_value by fwd_fees.
8. Set msg_balance_remaining to zero if mode has base modes SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE or SEND_MODE_CARRY_ALL_BALANCE.
9. Decrease remaining_balance by req.
10. Check that mode has flag SEND_MODE_DESTROY and base mode SEND_MODE_CARRY_ALL_BALANCE:
    • if so, then destroy the current account (contract) if remaining_balance is zero.

Example

Assume that

• value = 0.1 TON;
• mode = 80 = 00001010000 (that is, SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE + SEND_MODE_BOUNCE_ON_ACTION_FAIL);
• msg_balance_remaining = 0 TON (for instance, there was previous sending message action with mode SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE);
• remaining_balance = 2 TON;
• fwd_fees = 0.01 TON;
• gas_fees = 0.005 TON;
• action_fine = 0 TON.

Then the sending proceeds as follows:

• mode has flag SEND_MODE_BOUNCE_ON_ACTION_FAIL? Yes.
• mode has flag SEND_MODE_IGNORE_ERRORS? No.
• Set final_value = 0.1 TON.
• mode has base mode SEND_MODE_CARRY_ALL_BALANCE? No.
• mode has base mode SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE? Yes.
  • mode has flag SEND_MODE_PAY_FEES_SEPARATELY? No.
  • Increase final_value by msg_balance_remaining - gas_fees - action_fine = 0 TON - 0.005 TON - 0 TON = -0.005 TON.
  • Now, final_value = 0.1 TON - 0.005 TON = 0.095 TON.
• Set req = final_value = 0.095 TON.
• mode has flag SEND_MODE_PAY_FEES_SEPARATELY? No.
  • Decrease final_value by fwd_fees = 0.01 TON.
  • Now, final_value = 0.095 TON - 0.01 TON = 0.085 TON.
• Set msg_balance_remaining to zero (it is already zero).
• Decrease remaining_balance by req = 0.095 TON.
  • Now, remaining_balance = 2 TON - 0.095 TON = 1.905 TON.

Outgoing external messages

The algorithm above describes the sending process only for outgoing internal messages. However, outgoing external message can have only the following three modes: SEND_MODE_BOUNCE_ON_ACTION_FAIL, SEND_MODE_IGNORE_ERRORS, and SEND_MODE_PAY_FEES_SEPARATELY (use of any other leads to an error). SEND_MODE_PAY_FEES_SEPARATELY can be used, but have no effect. For outgoing external messages, SEND_MODE_BOUNCE_ON_ACTION_FAIL and SEND_MODE_IGNORE_ERRORS have the same behavior, i.e., to ignore almost all errors during the action phase processing.

There is no value field in external messages, so the forward fees are always deducted from account's balance.

Errors

The following errors can occur during the sending message flow:

• Simultaneous use of modes SEND_MODE_CARRY_ALL_BALANCE and SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE, 34 exit code.
• Modes except SEND_MODE_IGNORE_ERRORS, SEND_MODE_BOUNCE_ON_ACTION_FAIL, and SEND_MODE_PAY_FEES_SEPARATELY used for outbound external messages, 34 exit code.
• Source address in the outbound message is not equal to addr_none or the contract address, 35 exit code.
• Some problems with repacking the message body and StateInit into references if the message body or StateInit is too big to be located in place, 34 exit code.
• Malformed message structure, 34 exit code.
• Invalid destination address in the outbound message, 36 exit code.
• Not enough value to transfer with the message: all the inbound message value has been consumed, 37 exit code.
• Not enough funds for processing all message references, 40 exit code.
• The number of bits or references in StateInit and message body is too large, 40 exit code.
• Message has Merkle depth more than two, 40 exit code.
• If a message has only one SEND_MODE_CARRY_ALL_REMAINING_MESSAGE_VALUE base mode and final_value after the step 5 is negative, then an error with 37 exit code is thrown.
• If final_value after step 7 is negative, then an error with 37 exit code is thrown.
• If remaining_balance after step 9 is negative, then an error with 37 exit code is thrown.
• If remaining_balance after pay forward fees step is negative in a case of outgoing external message, then an error with 37 exit code is thrown.
• Problems related to extra-currency, exit codes 37, 44, 38.

The SEND_MODE_IGNORE_ERRORS mode ignore all the above errors except the four first ones (simultaneous use of modes, invalid modes for external messages, source address problems, and problems with repacking).

See also

• Sending messages with Tolk
• Handling incoming messages with Tolk