FunC Journey: Part 1

Article image

Greetings reader, this series of posts will be a guide to FunC development. To make your path clear and effective, I will give you a map and tips, you can use them to go through the lessons and thus understand FunC and possibly create your own application on TON.

The TON ecosystem is visible on the horizon, our journey begins....

TON blockchain smart contracts

Article image

TON network consists of TVMs (TON Virtual Machines). Smart contracts are programs stored on a blockchain that run when predetermined conditions are met. High-level language FunC is used to program smart contracts on TON blockchain. FunC programs are compiled into Fift assembler code, which generates corresponding bytecode for the TVM.

Any developer can create a smart contract and publish it on the TON network by paying a network fee. Any user can then call the smart contract to execute his code, again for a fee paid to the network.

Thus, with the help of smart contracts, developers can arbitrarily create and deploy complex user applications and services.

It is also important to note that published smart contracts have an address on the network.

The first thing we see when we enter the TON ecosystem is a "forest" of cells, in order to find a use for this and go further, you need to deal with data types, exceptions and functions in FunC.

Data types, functions and exceptions in TON

Article image

All persistent data in TON Blockchain is stored in trees of cells. Every cell has up to 1023 bits of arbitrary data in it and up to 4 references to other cells. Cells play a role of memory in stack-based TVM.

FunC program is essentially a list of function declarations/definitions and global variable declarations. any function declaration or definition starts with a common pattern. The pattern is following:

[<forall declarator>] <return_type> <function_name>(<comma_separated_function_args>) <specifiers>

where [ ... ] correspond to an optional entry.

Smart contracts on the TON network have two reserved methods that can be accessed.

  • recv_internal() is executed when inside TON itself, for example, when any contract refers to ours
  • recv_external() is executed when a request to the contract comes from the outside world, that is, not from TON

An important part of any smart contract is throwing exceptions if something goes wrong. Exceptions can be thrown by conditional primitives throw_if and throw_unless and by unconditional throw.

So that you can understand everything, I made a lesson in which you will write your first smart contract and in practice deal with the information that you just read. Link to the first lesson.

Congratulations, the forest of cells is passed, but in order for others to use our path, we will have to test it ..

Testing a smart contract

Article image

Distracted for a moment by thinking about the tests, you do not notice how the sage approaches you. He says that now there are two types of tests in TON.

V1 Tests

In the old version v1 tests, you need to write two functions for each test:

  • data function (or, as it would be more correct, a state function)
  • test function

Thus, for each test, we will first set the data / state, and then, in the test function, describe the logic of the test, causing exceptions every time the logic is violated.

Despite the fact that this is an old version of the tests, the sage urges you to pay attention to them in order to understand how testing in TON is generally arranged. How to test the smart contract, which we wrote in the first lesson with tests in version 1, can be read in the second lesson.

Link to the second lesson.

V2 Tests

As the sage leaves, he points to the distance, saying that there are also new tests in TON that you should pay attention to if you want to create tests faster.

In the new v2 tests, testing occurs through two functions that allow you to call smart contract methods:

  • invoke_method , which assumes no exception will be thrown
  • invoke_method_expect_fail which assumes an exception will be thrown

These special functions, we will call inside the test functions, which can return any number of values, all of them will be displayed when the tests are run in the report.

The name of each test function must start with __test. This way we can determine which functions are tests and which are just helpers. Lesson with examples on new v2 tests:

Link to the lesson with v2 tests.

As you move through the TON ecosystem, we gradually realize that without the concepts of registers and stack, it is impossible to create anything here, which means that this is a very important part of the journey through TON.

Stack and Registers

TON virtual machine is a stack machine. The order in which an element added to or removed from a stack is described as last in, first out. Therefore, we often have to read data in smart contracts, even if we do not use some of them. The function in the example below, we want to get the address, but we have to get the flags first, even though we don't use them.

slice parse_sender_address (cell in_msg_full) inline {
  var cs = in_msg_full.begin_parse();
  var flags = cs~load_uint(4);
  slice sender_address = cs~load_msg_addr();
  return sender_address;

Also, the state of the TVM is described by control registers, the most commonly used register in TON smart contracts is c4 - contains the root of persistent data, or simply the data section of the contract. This value is a Cell.

The journey deep into the ecosystem continues, we have several “smart contract base camps”, but how to organize communication between them?

Sending Messages

Article image

TON uses an actor model of communication between smart contracts. Each smart contract can receive one message, change its own state or send one or several messages per unit time. As a result, the entire blockchain, as well as a given contract, can scale up to host an unlimited amount of users and transactions. Lesson that introduces messages in TON:

Link to the lesson about messages.

Also the TON blockchain and the contracts it hosts can receive external messages — from other blockchains and the web in general. This means that one can send a message to a TON smart contract without having an on-chain account, and smart contracts can process and utilize external data for on-chain operations.

It is important to test our logic with messages, let's do it further.

Testing messages

Article image

Moving inside the ecosystem, you stumble upon strange stones covered with runes....

To test smart contracts with messages on, we will need to generate addresses. Objects in the TON are described by TL-B schemes, therefore, in order to understand what the address for testing should look like, we will have to look at the block scheme.

It becomes clear that the runes on the stones carry important information that will help in our journey.

In order to understand TL-B and I advise you to study: .

To help you figure out how to test messages, there is a lesson:

Link to the lesson about message tests.

Further path

In this article, we started our journey through the TON ecosystem with FunC programming language, I hope the first steps sparked your desire to move on.

Other parts: