TVM - Threaded Virtual Machine.

Realized 1 to 1 just like in Nikolai Durov’s whitepaper: tvm.pdf

What should you know about VM? It is simply a stacking virtual machine. We operate data in a stack (operations like "sum up 2 topmost numbers in the stack" or "swap the 2nd and the 10th variables in the stack").

You will not find a detailed technical description here since there is an excellent whitepaper by Nikolay. Current implementation had a number of new instructions and fixes.

Code is Simply Data

The code is just stored in the account memory. It can be delivered along with messages and re-written. There is a tvm.setcode(code) operation that changes the code of your contract (starting with the subsequent transaction) and even tvm.setCurrentCode(code) that applies the new code right to the current transaction. We have article on "smart contracts" chapter describes the process of updating contracts.

Messages and Funds

In the scope of asynchronous architecture, all interaction of contracts with each other is carried out via message sending.

Here are the steps:

• A contract receives an EXTERNAL message from the outside world. If the contract agrees to pay for it, a transaction is launched. As a result of it, the contract may create up to 255 of outcoming internal messages. This outcoming internal message has the address of the destination contract, the function to call in it, and what arguments to pass.
• The destination contract receives an incoming internal message and launches a transaction, the result of which is again the creation of outcoming internal messages.

External messages are simple. 10k of gas credit are allocated to external messages, and if a contract does not agree to supply the gas to pay for the transaction, then the message will simply be discarded, and the transaction will not start.

But with internal messages, everything is more complicated. When a contract receives an internal message, a transaction is started. Logically, in most cases the calling contract should pay for the gas for this transaction type, and not the called contract. But at the same time, it is obvious that the calling contract must control exactly how much gas it is willing to pay. What further complicates things is that contracts can find themselves in different shards, and one shard cannot spend money of another shard.

Therefore, in VENOM, all outgoing messages are appended with value (VENOMs). When a contract receives a message, the gas is paid out of the money attached to this message, and if the money in the message runs out and the contract does not want to continue paying, then the transaction will run out of gas. If, after the transaction is completed, there is still money left in the message, then it will be added to the contract’s account (or the contract can send the change back).

All internal messages have to carry some amount of money with them. Even if the contract agrees to pay for the message, the message must have enough coins to pay for the initial checks (until it gets to tvm.accept()).

If we consider the issue of funds and paying for gas in comparison, for example, with Ethereum, ether has two entities: smart contracts with their balances and user's account with its balance which starts the transaction. Even in the case the user's account transfers ether to the smart contract, the fee is still paid separately from the user account balance. However, VENOM blockchain has other entities, namely: the message and the account of the smart contract itself along with its balance.

If the message is internal, it always carries with it some amount of VENOMs. Before the start of the computation stage of the transaction, all VENOMs attached to the message are added to the account balance, and address(this).balance will show the already topped-up balance. We can see how much funds were attached to the message in the variable msg.value. The key point is that the transaction cannot spend more money on gas from the account balance than msg.value provided that the contract will not explicitly call tvm.accept() by agreeing to pay for the transaction from its balance if needed.

Gas

Gas price is constant in VENOM. In the asynchronous environment, we send a message to another smart contract and attach the required amount of VENOMs to pay for the transaction. By default, the message will be delivered in 2-5 seconds, but it may take indefinite time under higher load. This is why the payment for gas is a constant value and not dependent on demand, since the developers and users need to clearly understand how many VENOMs they need to add to the message to ensure the amount needed to pay for the entire transaction chain. Blockchain handles the demand increase by the increase of the number of threads rather than the transaction price. An exceptionally high load may result in the increase of the time of issuing master blocks and the speed of finalizing transaction chains.

In the future, we plan to introduce dynamic pricing for gas, but it will have a price cap due to the same reasons. Likely there will be maximum gas price (as now), but the price may go down when the load on network declines.

What we pay for:

• Calculations, as usual.
• Loading memory cells. There are some twists, we will cover them later in the part on BoC.
• Creating outcoming messages and receiving incoming ones, if they are external and we agreed to pay for them. The fee depends on the message size.
• Storage. Every contract pays a rental fee for the storage of its own code and its state data. This fee is withdrawn each time a message is sent to you (for all the time that has elapsed since the last transaction). If the balance of your contract falls below 0, the further calls to the contract will cease to work until you replenish the balance. If the balance falls below 0 VENOM the contract will be frozen, with only the hash of data and code remaining while everything else is deleted. The unfreezing process is complicated, you need to replenish your contract and provide its data and code the moment it is frozen. If the balance falls below -0.1 VENOM (for workchain 0, a network parameter, can be changed) it will be deleted. It means that you do not want to store outdated or irrelevant data in the BC. In return, you get a low cost of writing into the BC since data is not stored eternally. How to live with it is discussed in the article "Distributed Programming" of the chapter "Smart Contracts."

You can find the exact gas cost formulas here.

Parameters of internal message creation

When you create any internal message by calling the method of other contract or just send him money, you need to set up three parameters:

address.transfer(uint128 value, bool bounce, uint16 flag);

• value - the amount of VENOM you want to attach to the message.
• bounce - Boolean flag that indicates whether we need to try to create a return message should an error occurs during the processing of the message or there is no contract deployed on the destination address. True - send all remaining value back with a note that an error occurred. False - all VENOMs will just remain in the destination contract.
• flag - special flag for a finer work with the amount of value to add to the outcoming message. Default flag is 0 - send with message value VENOMs minus costs for creating this message.

function updateValueOnChildren(
    address children,
    uint256 new_variable_value
) external {
    require(msg.pubkey() == tvm.pubkey(), AErrors.error_message_sender_is_not_my_owner);
    tvm.accept();
    // In IB interface, call 'setValue' function.
    // Flag is 0 by default, pay for the message creation from
    // the value attached to the message
    // bounce: true - on any error send all VENOMs back.
    // Compiler was written for everscale, so we using keyword 'ever'
    // to indicate coins. 0.5 ever = 500_000_000 nano coins.
    B(children).setValue{value: 0.5 ever, bounce: true, flag: 0}(new_variable_value);
}

// Contract B
address static myOwner;
uint256 stored_variable_value;

function setValue(
    uint256 new_variable_value
) external {
    require(msg.sender == myOwner, BErrors.error_message_sender_is_not_my_owner);

    // Here we won't call tvm.accept() because we don't want 
    // the incoming message to be able to spend money on the smart contract account. 
    stored_variable_value = new_variable_value;

    // We send the rest of the remaining value back to the sender.
    // value - 0, bounce - false, flag - 64
    // flag 64 - send all the value was in incoming message minus value spent on gas
    msg.sender.transfer(0, false, 64);
}

Above you can see a standard pattern of gas calculation. Usually we do not calculate the exact amount of gas required for a call, but just send it with an extra and return change to the person who initiated the transaction chain. This is because we have to send gas in the worst scenario, and there is some change in any case.

Flag can be:

• 0 - send the amount of VENOMs indicated in VALUE minus the cost of sending the message.
• 64 - send VALUE VENOM + all VALUE that remained in the incoming message after we paid for gas (returning change + value).
• 128 - send all coins that remained on the balance after the sending of previous messages.

The values above may be summed up with the values below to get extra properties (can be combined):

• • 1 - means that message creation and delivery fee will be paid from the contract account.
• • 2 - means that any errors arising while processing this message during the action phase should be ignored. For example, if you lack enough money to pay for a message, the transaction will not be aborted, just this message will skipped.
• • 32 - means that the current account must be destroyed if its resulting balance is zero. For example, flag: 128 + 32 is used to send all balance and destroy the contract.

In most cases you will use the following flags: 0, 1, 3 (0 + 1 + 2), 64, 128.

Everything is a bag of cells

All data in blockchain is stored and sent in a structure called the Bag of Cell. Perhaps it would be possible to abstract the virtual machine from this structure, but Nikolay did not do so. In general, all data stored in the contract (not the code, the code is separate, but also the Tree of Cell is stored in the contract :-)) is stored in one data cell with links to subcells.

The TVMCell is a structure that has 1023 Bits of data and 4 references to its child cells. A cell reference is the HASH of that cell.

So we have a single-way connected graph, where each node can have 4 descendants. And we need to pack all smart-contract data or messages into a cell with sub-cells.

Threaded Solidity abstracts us from manual work with cells and does everything for us. But there are rare cases when you will have to do it yourself. In order to do this, there are special primitives in Solidity.

Some BoC properties to understand.

The entire state of the contract is BoC. This is one cell with as many child cells as you like. T-Solidity takes care of work with states for us, but you need to understand that, because of BC’s tree structure, we normally do not write contracts with a lot of data.

In order to illustrate how it works, consider (schematically) how a dictionary could be implemented in ToC. This can be a tree-like structure:

Each circle in the picture is a separate cell. To get the value by key 2, VM needs to load a cell of depth 0, then depth 1 and then depth 2. We have to pay for gas every time a cell is loaded. And if we change the value by key 2, we will need to recalculate all references from the cell with the value of the root cell because the cell reference is a hash (cell.data + cell.refs). So, links to all cells along the way will change and we will need to change them from bottom to top.

So, the more elements our dictionary has, the deeper the cell will be and the more expensive it will be to work with. For a dictionary, the cost of gas will increase to O(log n) in a worst-case scenario. (In reality, everything would be more complicated but O (log n) can be useful to look at as a worst-case scenario.)

Now, if we are creating an ERC20 token, then the more owners this token has, the more expensive the gas will be to use this contract (the size of the owner-number map will grow). And although O(Log n) does not sound scary at all, and the cost of working with the map will increase very, very slowly after the first hundred elements, and then even slower after that, there we have a storage fee that grows linearly.

If you have accounts in your ERC-20 token that contain pennies, then the fees for holding these accounts will greatly exceed the value of these accounts over the years. Therefore, in Venom it is customary to make separate contracts for separate token accounts, which themselves pay for their storage. We will look into the paradigm of distributed programming in the next chapter.

Next, we recommend that you switch to the chapter on smart contract. The next article of this chapter, "Transaction executor," is intended for experienced smart contracts developers.