Message Modes Cookbook
Page is under active development
Understanding the different modes and flags available for sending messages is important to ensure that your smart contracts behave correctly. While message modes section provided detailed descriptions of these modes and flags, in this section we will illustrate their practical application with specific examples.
Message value and account balance
There are 2 ways to pay for blockchain action:
- from message value.
- from contract balance
Typically it's charged from contract balance, but in specific cases it will use part of the message value. The transaction fees used in these examples are hypothetical and are used for illustrative purposes only, any fees other than message forward are out of scope of this article.
Note: Actual transaction fees will vary depending on blockchain configuration, code of the smart contract and other factors. When message is received, part of it will be consumed for gas and storage fees. Please check how get_balance works to understand transaction state better. You can check this example as a real-world confirmation.
1. Send a regular message
State before transaction: Account A has 1 TON, Account B has 1 TON
A sent 0.1 TON to B, msg_fwd_fees are 0.004 TON, actual received value will be 0.096 TON, fwd_fee and action_fee deducted from value.
State after transaction: Account A has 0.9 TON, Account B has 1.096 TON
| Mode and Flags | Code |
|---|---|
mode = 0, no flag | send_raw_message(msg, 0) |
2. Send a regular message, no bounce the message on error and ignore it
State before transaction: Account A has 1 TON, Account B has 1 TON
A sent 0.1 TON to B, msg_fwd_fees are 0.004 TON, actual received value will be 0.096 TON, fwd_fee and action_fee deducted from value.
In case of an error during transaction processing, the message will not bounce and will be ignored.
State after transaction: Account A has 0.9 TON, Account B has 1.096 TON
Funds included with an ignored message will still be credited to the receiving address.
If no errors the result is the same as mode = 0.
| Mode and Flags | Code |
|---|---|
mode = 0, flag = 2 | send_raw_message(msg, 2) |
3. Send a regular message and bounce the message on action error
State before transaction: Account A has 1 TON, Account B has 1 TON
A sent 0.1 TON to B, msg_fwd_fees are 0.004 TON, actual received value will be 0.096 TON, fwd_fee and action_fee deducted from value.
In case of an error during action phase, the message will bounce and total_fee + fwd_fee will be deducted from value.
State after transaction with error: Account A has 1 - (total_fee + fwd_fee) TON, Account B has 1 TON
If no errors the result is the same as mode = 0.
| Mode and Flags | Code |
|---|---|
mode = 0, flag = 16 | send_raw_message(msg, 16) |
4. Send a regular message with separate fees
State before transaction: Account A has 1 TON, Account B has 1 TON
A sent 0.1 TON to B, msg_fwd_fees are 0.004 TON, actual received value will be 0.1 TON, fwd_fee and action_fee deducted from balance.
State after transaction: Account A has 0.896 TON, Account B has 1.1 TON
| Mode and Flags | Code |
|---|---|
mode = 0, flag = 1 | send_raw_message(msg, 1) |
5. Send a regular message with separate fees and bounce the message on error
State before transaction: Account A has 1 TON, Account B has 1 TON
A sent 0.1 TON to B, msg_fwd_fees are 0.004 TON, actual received value will be 0.1 TON, fwd_fee and action_fee deducted from balance.
In case of an error during action phase, the message will bounce and total_fee + fwd_fee will be deducted from value.
State after transaction with error: Account A has 1 - (total_fee + fwd_fee) TON, Account B has 1 TON
If no errors the result is the same as mode = 1.
| Mode and Flags | Code |
|---|---|
mode = 0, flag = 1 + 16 = 17 | send_raw_message(msg, 17) |
6. Carry remaining value with new message
State before transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON
A sent 0.1 TON to B after that B sent 0.5 TON to C with mode = 64, msg_fwd_fees are 0.004 TON, actual received value will be 0.6 TON, total_fee + fwd_fee deducted from value.
State after transaction: Account A has 0.896 TON, Account B has 0.5 TON, Account C has 1.6 - (total_fee + fwd_fee) TON
You might check this example
| Mode and Flags | Code |
|---|---|
mode = 64, no flag | send_raw_message(msg, 64) |
7. Carry remaining value with new message with separate fees
State before transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON
A sent 0.1 TON to B after that B sent 0.5 TON to C with mode = 65, msg_fwd_fees are 0.004 TON, actual received value will be 0.6 TON, total_fee + fwd_fee deducted from balance.
State after transaction: Account A has 0.896 TON, Account B has 0.5 - (total_fee + fwd_fee) TON, Account C has 1.6 TON
You might check this example
| Mode and Flags | Code |
|---|---|
mode = 64, flag = 1 | send_raw_message(msg, 65) |
8. Carry remaining value and bounce the message on error
State before transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON
A sent 0.1 TON to B after that B sent 0.5 TON to C with mode = 80, msg_fwd_fees are 0.004 TON, actual received value will be 0.6 TON, total_fee + fwd_fee deducted from value.
In case of an error during action phase, the message will bounce and total_fee + fwd_fee will be deducted from value.
State after transaction with error: Account A has 1 - (total_fee + fwd_fee) TON, Account B has 1 TON, Account C has 1 TON
If no errors the result is the same as mode = 64.
| Mode and Flags | Code |
|---|---|
mode = 64, flag = 16 | send_raw_message(msg, 80) |
9. Carry remaining value with new message with separate fees and bounce the message on error
State before transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON
A sent 0.1 TON to B after that B sent 0.5 TON to C with mode = 80, msg_fwd_fees are 0.004 TON, actual received value will be 0.6 TON, total_fee + fwd_fee deducted from balance.
In case of an error during action phase, the message will bounce and total_fee + fwd_fee will be deducted from value.
State after transaction with error: Account A has 1 - (total_fee + fwd_fee) TON, Account B has 1 TON, Account C has 1 TON
If no errors the result is the same as mode = 65.
| Mode and Flags | Code |
|---|---|
mode = 64, flag = 16 + 1 | send_raw_message(msg, 81) |
10. Send all received tokens together with the contract balance
State before transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON
A sent 0.1 TON to B after that B sent 0.5 TON to C with mode = 128, msg_fwd_fees are 0.004 TON, actual received value will be 1.1 - total_fee TON, total_fee deducted from value.
State after transaction: Account A has 0.896 TON, Account B has 0 TON, Account C has ~2.09 TON
| Mode and Flags | Code |
|---|---|
mode = 128, no flag | send_raw_message(msg, 128) |
11. Send all received tokens together with the contract balance and bounce the message on error
State before transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON
A sent 0.1 TON to B after that B sent 0.5 TON to C with mode = 144, msg_fwd_fees are 0.004 TON, actual received value will be 1.1 - total_fee TON, total_fee deducted from value.
State after transaction with error: Account A has 1 - (total_fee + fwd_fee) TON, Account B has 1 TON, Account C has 1 TON
If no errors the result is the same as mode = 128.
| Mode and Flags | Code |
|---|---|
mode = 128, flag = 16 | send_raw_message(msg, 144) |
12. Send all received tokens together with the contract balance and destroy smart-contract
State before transaction: Account A has 1 TON, Account B has 1 TON, Account C has 1 TON
A sent 0.1 TON to B after that B sent 0.5 TON to C with mode = 160, msg_fwd_fees are 0.004 TON, actual received value will be 1.1 - total_fee TON, total_fee deducted from value.
State after transaction: Account A has 0.896 TON, Account B has 0 TON and nonexist, Account C has ~2.09 TON
When the balance reaches 0 TON destroy the contract.
| Mode and Flags | Code |
|---|---|
mode = 128, flag = 32 | send_raw_message(msg, 160) |