HomeGuidesAPI ReferenceChangelog
GuidesAPI ReferenceCommunityDiscordBlogFAQBug BountyAnnouncementsChange Log
Guides

TRON Virtual Machine (TVM)

TRON Virtual Machine (TVM) is the runtime environment for TRON smart contracts, and each node in the network maintains a TVM entity. The TRON protocol keeps the continuous, uninterrupted, and immutable operation of this state machine. At any given block in the chain, TRON has one and only one 'canonical' state, and the TVM is what defines the rules for computing a new valid state from block to block.

From Ledger to State Machine

The analogy of a 'distributed ledger' is often used to describe blockchains like Bitcoin, which enables a decentralized currency using fundamental tools of cryptography. A cryptocurrency behaves like a 'normal' currency by adhering to the rules that govern what can and cannot be done to modify the ledger. For example, a Bitcoin address cannot spend more Bitcoin than it has previously received. These rules underpin all transactions on Bitcoin.

While TRON has its own native cryptocurrency TRX that follows almost exactly the same intuitive rules, it also enables a much more powerful functionality: smart contracts. With this more complex feature, instead of a simple distributed ledger, TRON is actually a distributed state machine. TRON's state is a large data structure which holds not only all accounts information, but also a machine state, which can change from block to block according to a pre-defined set of rules, and can execute arbitrary machine code.

State Transition Function

The TVM behaves like a mathematical function: Given an input, it produces a deterministic output. It therefore is quite helpful to more formally describe TRON as having a state transition function:

Y(S, T) = S'

Given an old valid state (S) and a new set of valid transactions (T), the TRON state transition function Y(S, T) produces a new valid output state S'.

State

In the TRON network, the state is an enormous data structure called Merkle Trie, which keeps all accounts linked by hashes and reducible to a single root hash stored on the blockchain.

Transactions

Transactions are cryptographically signed instructions from accounts. They are divided into two categories, system contract transactions and smart contract transactions, in which smart contract transactions include those resulting in contract message calls and contract creation.

Contract creation generates a new contract account containing compiled smart contract bytecode. Whenever another account makes a message call to that contract, it executes the corresponding bytecode on the TVM.

TVM Instructions

The TVM executes as a stack machine with a depth of 1024 items. Each item is a 256-bit word, which was chosen for the ease of use with 256-bit cryptography (such as Keccak-256 hashes or secp256k1 signatures).

Compiled smart contract bytecode executes as a number of TVM opcodes, which perform standard stack operations like XOR, AND, ADD, and SUB. The TVM also implements a number of blockchain-specific stack operations, such as ADDRESS, BALANCE, and BLOCKHASH. For more opcodes, please refer to TRON opcodes

The below flowchart shows how TVM works:

The flow involves the following steps:

  • The compiler compiles the smart contract into bytecode, which is readable and executable on the TVM.
  • The TVM processes data according to the opcode.
  • The TVM accesses blockchain data and invokes external data interfaces through the Interoperation layer.
  • When the TVM finishes execution, the status is written into the block, and the user can query the execution result and status through the API.

TVM vs EVM

The TVM exhibits fundamental compatibility with the Ethereum Virtual Machine (EVM), with notable distinctions in the following aspects:

  1. The TVM employs an Energy model instead of the gas model. energyPrice is a network parameter (it can be changed by committee proposals), currently set at 210 sun on the Mainnet. Unlike the fluctuating gas prices and the presence of a basefee in the EVM, the TVM's GASPRICE and BASEFEE opcodes both return the energyPrice.
  2. The Energy consumption of the major TVM opcodes aligns with their EVM counterparts, with certain opcodes exhibiting lower Energy costs, such as SLOAD and CALL.
  3. The prefix for contract addresses generated via CREATE2 on the TVM is different from that of the EVM. The TVM utilizes the 0x41 prefix, determined by the following formula (where ++ represents string concatenation):
    keccak256(0x41++ address ++ salt ++ keccak256(init_code))[12:]
    
  4. TRX can be transmitted to contracts through two mechanisms: standard transfers and TriggerSmartContract invocations carrying a callValue. Standard transfers bypass the execution of the contract's fallback function.

Differences in Instructions

InstructionTVMEVM
DIFFICULTY (0x44)Returns 0Returns the current block difficulty
GASLIMIT (0x45)Returns 0Returns the current block’s gaslimit
GASPRICE (0x3A)Returns energyPriceReturns the current gasPrice
BASEFEE (0x48)Returns energyPriceReturns the current block’s baseFee
CREATE2 (0xf5)Contract address prefix: 0x41Contract address prefix: 0xff

Differences in Precompiled Contracts

Precompiled Contract AddressTVMEVM
Ripemd160 (0x03)Computes SHA-256 twiceComputes SHA-256 once
0x09BatchValidateSign (used for batch signature verification)Blake2F

New Features of the TVM

Instructions

Instruction Function
TRC-10
CALLTOKEN (0xd0) Invokes contract with TRC-10 token
TOKENBALANCE (0xd1) Queries the balance of TRC-10 token for an address
CALLTOKENVALUE (0xd2) Retrieves the TRC-10 token value associated with the current call
CALLTOKENID (0xd3) Retrieves the ID of the TRC-10 token involved in the current call
TIP-44
ISCONTRACT (0xd4) Checks if a given address is a contract address
TIP-157 freeze/Unfreeze Functions
FREEZE(0xd5) Stake TRX to acquire resources
UNFREEZE(0xd6) Unstake TRX, releasing acquired resources
FREEZEEXPIRETIME(0xd7) Queries the expiration time of a FREEZE operation
TIP-467 freezeV2/UnfreezeV2 Functions
FREEZEBALANCEV2 (0xda) Stake TRX to acquire resources (V2)
UNFREEZEBALANCEV2 (0xdb) Unstake TRX, releasing acquired resources (V2)
CANCELALLUNFREEZEV2 (0xdc) Cancels all pending UNFREEZE operations (V2)
WITHDRAWEXPIREUNFREEZE(0xdd) Withdraws expired unstaked TRX
DELEGATERESOURCE (0xde) Delegates resources to another address
UNDELEGATERESOURCE (0xdf) Cancels resource delegation
TIP-721 Contract Voting Related Functions
VOTEWITNESS (0xd8) Votes for a Super Representative
WITHDRAWREWARD (0xd9) Withdraws accumulated voting rewards

Precompiled Contracts

Precompiled Contract Function
TIP-60
ValidateMultiSign (0x0a) Multi-signature verification
TIP-43
BatchValidateSign (0x09) Batch signature verification
TIP-271 Contract Voting-Related Functions
RewardBalance (0x1000005) Retrieves voting reward balance
IsSrCandidate (0x1000006) Queries whether an address is an srCandidate
VoteCount (0x1000007) Queries the number of votes a certain address has given to a certain Witness
TIP-467 freezeV2/UnfreezeV2 Functions
GetChainParameter(0x100000b) Queries the specified chain parameters
AvailableUnfreezeV2Size (0x100000c) Queries the available length of the unfreeze queue for the target address (V2)
UnfreezableBalanceV2 (0x100000d) Queries the unfreezable balance of the specified resource type for the target address (V2)
ExpireUnfreezeBalanceV2(0x100000e) Queries the withdrawable amount at a specified timestamp for a target address (V2)
DelegatableResource(0x100000f) Queries the delegatable amount of the specified resource type for the target address
ResourceV2(0x1000010) Queries the amount of the specified resource type delegated from the specified address to the target address (V2)
CheckUnDelegateResource(0x1000011) Checks whether the contract can reclaim the specified amount of resources of a specific resource type that have been delegated to the target address
ResourceUsage(0x1000012) Queries the usage and recovery time of the specified resource type for the target address.
TotalResource(0x1000013) Queries the total amount of available resources of the specified resource type for the target address
TotalDelegatedResource (0x1000014) Queries the amount of delegated resources of a specified resource type for the target address
TotalAcquiredResource (0x1000015) Queries the total amount of the specified resource type acquired by the target address through delegation

Discussions regarding compatibility-related solutions are still ongoing. You can participate in the current discussions on GitHub Issues.