On the TON (The Open Network) blockchain, the execution of smart contracts relies on the TVM (TON Virtual Machine). To ensure the robustness and correctness of contracts, developers need to have a deep understanding of TVM exit codes. This article will detail the meanings, categories, and their application in debugging smart contracts.
Overview of TVM Exit Codes
When executing smart contracts, TVM uses a 16-bit unsigned integer as the exit code (exit_code). This exit code is a crucial communication channel between the VM and the outside world, indicating the state of contract execution:
- When the exit_code is 0 or 1, it indicates that the contract executed successfully.
- When the exit_code is greater than 1, it signifies that an error occurred during contract execution, which could lead to transaction rollback or bounce.
Standard Exit Codes and Their Meanings
The standard exit codes of TVM are divided into two phases: Compute Phase and Action Phase. Below are the standard exit codes for these phases and their meanings.
Compute Phase Exit Codes
Successful Execution Exit Codes
- 0: Standard successful execution exit code, indicating that the contract executed successfully as expected.
- 1: Alternative successful execution exit code, typically used for successful execution in specific scenarios.
Error Exit Codes
- 2: Stack underflow, the last opcode consumed more elements than available on the stack, which may indicate a type error in the assembly declaration.
- 3: Stack overflow, the value stored on the stack exceeds the allowed value in this version of TVM.
- 4: Integer overflow, the integer does not fit within -2256 ≤ x < 2256 or a division by zero operation occurred.
- 5: Integer out of expected range.
- 6: Invalid opcode, the instruction is unknown in the current TVM version.
- 7: Type checking error, the parameters of the primitive have incorrect value types, which may indicate a type error in the assembly declaration.
- 8: Cell overflow, it is impossible to write to the builder because the operation would result in more than 1023 bits or 4 references.
- 9: Cell underflow, an attempt was made to read more bits or references than exist when reading from a slice primitive.
- 10: Dictionary error, an error occurred during the processing of the dictionary (hash map).
- 11: Unknown error, commonly due to an attempt to call a get method whose ID was not found in the code.
- 12: An impossible situation thrown by TVM.
- 13: Gas exhaustion error, TVM throws this error when the remaining gas becomes negative.
- -14: Gas exhaustion error, the same as 13, but negative, indicating it cannot be forged.
Action Phase Exit Codes
- 32: Invalid operation list, if the c5 register contains an object that cannot be resolved after execution.
- -32: Method ID not found, the same as 32, but for TonLib return values.
- 33: Operation list too long.
- 34: Operation invalid or not supported.
- 35: Invalid source address in the outbound message.
- 36: Invalid destination address in the outbound message.
- 37: Insufficient TON, too much TON was sent in the message (or insufficient TON after fees).
- 38: Insufficient additional tokens.
- 40: Insufficient funds to process the message, when only enough gas covers part of the message, but not completely.
- 43: Exceeded the maximum number of cells in the library or the maximum depth of the Merkle tree.
Special Exit Code
- 0xffff (Decimal 65535): This is a special exit code that typically means the contract does not recognize the received opcode. This code is set by developers when writing contracts to handle unknown operations.
Conclusion
Understanding TVM exit codes is crucial for the development and debugging of TON smart contracts. Developers should use these exit codes to identify and fix issues within their contracts, ensuring stable operation on the TON blockchain. By gaining a deep understanding of these exit codes, developers can better grasp the execution state of their contracts, improving their robustness and reliability.