18 KiB
| language | filename | contributors | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Tact | tact.tc |
|
Tact language is used to program smart contracts on the The Open Network blockchain. Contract logic is executed in TVM, the stack-based TON Virtual Machine.
Tact is a statically typed, but language was designed to be friendly for developers with JS and Python background.
This page is based on Tact-by-Example. You can use this resource to play around with contracts and check out the interactive features.
Basic syntax, function definition
// Single line comment
// This is a multi-line comment
// this is a comment in the comment
get fun greeting(): String {
// This is a function that returns "hello world" message
// Return type is specified after a colon :
return "hello world";
}
A Simple Counter contract
This is a simple counter contract that allows users to increment its value.
This contract has a state variable val that persists between contract calls
- the counter value. When persisted, this variable is encoded as
uint32- a 32-bit unsigned integer. Contracts pay rent in proportion to the amount of persistent space they consume, so compact representations are encouraged.
State variables should be initialized in init() that runs on deployment of
the contract.
Messages
The actor model is a model of concurrent computation and is at the heart of TON smart contracts. Each smart contract can process one message at a time, change its own state, or send one or several messages. Processing of the message occurs in one transaction, that is, it cannot be interrupted. Messages to one contract are processed consequently one by one. As a result, the execution of each transaction is local and can be parallelized at the blockchain level, which allows for on-demand throughput horizontal scaling and hosting an unlimited number of users and transactions.
Receiving messages
This contract can receive messages from users. Unlike getters that are just read-only, messages can do write operations and change the contract's persistent state. Incoming messages are processed in receive() methods as transactions and cost gas for the sender.
After deploying the contract, send the increment message by pressing the Send increment button in order to increase the counter value by one. Afterwards, call the getter value() to see that the value indeed changed.
contract Counter {
// Tact allows to create a contract
// persistent state variable of type Int to hold the counter value
val: Int as uint32;
// initialize the state variable when contract is deployed
init() {
self.val = 0;
}
// handler for incoming increment messages that change the state
receive("increment") {
self.val = self.val + 1;
}
// read-only getter for querying the counter value
get fun value(): Int {
return self.val;
}
}
The Deployable Trait
Tact doesn't support classical class inheritance, but contracts can implement
traits. One of the commonly used traits is Deployable. It implements a simple
receiver for the Deploy message which helps deploy contracts in a standard way.
All contracts are deployed by sending them a message. This can be any message,
but best practice is to designate the special Deploy
message for this purpose.
This message has a single field, queryId, which is provided by the deployer
(normally zero). If the deploy succeeds, the contract will reply with the
message DeployOk and echo the same queryId in the response.
If you're using Tact's auto-generated TypeScript classes to deploy, sending the deploy message should look like:
const msg = { $$type: "Deploy", queryId: 0n };
await contract.send(sender, { value: toNano(1) }, msg);
You can see the implementation of the trait here. Notice that the file deploy.tact needs to be imported from the standard library using the import keyword.
// this trait has to be imported
import "@stdlib/deploy";
// the Deployable trait adds a default receiver for the "Deploy" message
contract Counter with Deployable {
val: Int as uint32;
init() {
self.val = 0;
}
receive("increment") {
self.val = self.val + 1;
}
get fun value(): Int {
return self.val;
}
}
Integers
Tact supports a number of primitive data types that are tailored for smart contract use.
Int is the primary number type. Math in smart contracts is always done
with integers and never with floating points since floats are unpredictable.
The runtime type Int is always 257-bit signed, so all runtime calculations
are done at 257-bit. This should be large enough for pretty much anything you
need as it's large enough to hold the number of atoms in the universe.
Persistent state variables can be initialized inline or inside init().
If you forget to initialize a state variable, the code will not compile.
State costs
When encoding Int to persistent state, we will usually use smaller
representations than 257-bit to reduce storage cost.
The persistent state size is specified in every declaration of
a state variable after the as keyword.
Storing 1000 257-bit integers in state costs about 0.184 TON per year. Storing 1000 32-bit integers only costs 0.023 TON per year by comparison.
import "@stdlib/deploy";
contract Integers with Deployable {
// contract persistent state variables
// integers can be persisted in state in various sizes
// range -2^256 to 2^256 - 1 (takes 257 bit = 32 bytes + 1 bit)
i1: Int as int257 = 3001;
i2: Int as uint256; // range 0 to 2^256 - 1 (takes 256 bit = 32 bytes)
// range -2^255 to 2^255 - 1 (takes 256 bit = 32 bytes)
i3: Int as int256 = 17;
i4: Int as uint128; // range 0 to 2^128 - 1 (takes 128 bit = 16 bytes)
// range -2^127 to 2^127 - 1 (takes 128 bit = 16 bytes)
i5: Int as int128;
i6: Int as coins; // range 0 to 2^120 - 1 (takes 120 bit = 15 bytes)
// range 0 to 18,446,744,073,709,551,615 (takes 64 bit = 8 bytes)
i7: Int as uint64 = 0x1c4a;
// range -9,223,372,036,854,775,808 to 9,223,372,036,854,775,807
// (takes 64 bit = 8 bytes)
i8: Int as int64 = -203;
i9: Int as uint32 = 0; // range 0 to 4,294,967,295 (takes 32 bit = 4 bytes)
// range -2,147,483,648 to 2,147,483,647 (takes 32 bit = 4 bytes)
i10: Int as int32 = 0;
i11: Int as uint16 = 0; // range 0 to 65,535 (takes 16 bit = 2 bytes)
i12: Int as int16 = 0; // range -32,768 to 32,767 (takes 16 bit = 2 bytes)
i13: Int as uint8 = 0; // range 0 to 255 (takes 8 bit = 1 byte)
i14: Int as int8 = 0; // range -128 to 127 (takes 8 bit = 1 byte)
init() {
// we can define numbers in hex (base 16)
self.i2 = 0x83dfd552e6372;
self.i4 = 1507998500293440234999; // we can define numbers in decimal
self.i5 = pow(10, 9); // this is 10^9 = 1,000,000,000
self.i6 = ton("1.23"); // easy to read coin balances
// (coins type is nano-tons, like cents, just with 9 decimals)
}
receive("show all") {
dump(self.i1);
dump(self.i2);
dump(self.i3);
dump(self.i4);
dump(self.i5);
dump(self.i6);
dump(self.i7);
dump(self.i8);
}
get fun result(): Int {
return self.i1;
}
}
Bools, Addresses, Strings, Operators and Constants
Bool
Bool can be used for boolean variables
b1: Bool = true;
b2: Bool = false;
Address
Address is another primitive data type. It represents standard addresses on the TON blockchain. TON is divided into multiple chains called workchains. One of the internal fields of the address is the workchain id: 0 - The standard workchain, for regular users. Your contracts will be here. -1 - The masterchain, usually for validators.
// bouncable (same foundation wallet)
a1: Address = address("EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N");
// non-bounceable (same foundation wallet)
a2: Address = address("UQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqEBI");
String
Tact has basic support for strings. Strings support unicode and don't have any special escape characters like \n. Strings are immutable. Once a sequence of characters is created, this sequence cannot be modified. If you need to concatenate strings in run-time, you can use a StringBuilder. This object handles gas efficiently and supports append() of various types to the string.
s1: String = "hello world";
sb: StringBuilder = beginString();
sb.append(self.s1);
Integer Operations
Addition, subtraction, multiplication, division, modulo, shift left and right, minimum and maximum numbers, absolute value
i: Int = -12; // temporary variable, runtime Int type is always int257
i = i1 * 3 + (i2 - i); // basic math expressions
i = i1 % 10; // modulo (remainder after division), 3001 % 10 = 1
i = i1 / 1000; // integer division (truncation toward zero), 3001 / 1000 = 3
i = i1 >> 3; // shift right (multiply by 2^n)
i = i1 << 2; // shift left (divide by 2^n)
i = min(i2, 11); // minimum between two numbers
i = max(i2, 66); // maximum between two numbers
i = abs(-1 * i2); // absolute value
Constants
Unlike variables, constants cannot change. Their values are calculated in compile-time and cannot change during execution.
const StateUnpaid: Int = 0;
Getters, Receivers and Messages
Getters
Getters are special contract functions that allow users to query information from the contract. Contract methods starting with the prefix get fun are all getters. Calling getters is free and does not cost gas. Getters are read-only, they cannot change the contract persistent state. A contract cannot execute a getter of another contract. Getters are only executable by end-users off-chain.
count: Int as uint32 = 17;
get fun counter(): Int {
return self.count;
}
Receivers
Contract methods named receive() are the handlers that process each incoming message type. Tact will automatically route every incoming message to the correct receiver listening for it according to its type. A message is only handled by one receiver.
Handler for "increment" textual message - this is a textual string message, these cannot carry input arguments
receive("increment") {
self.val = self.val + 1;
}
Messages
Messages are defined using the message keyword. They can carry input arguments. For integers, you must define the encoding size, just like in state variables.
Handler for the "Add" message - this is a binary message that has an input argument (amount)
receive(msg: Add) {
self.val = self.val + msg.amount;
}
Structs
Structs allow you to combine multiple primitives together in a more semantic way. Structs can define complex data types that contain multiple fields of different types. They can also be nested.
// Normal struct
struct Point {
x: Int as int64;
y: Int as int64;
}
// Nested struct
struct Params {
name: String = "Satoshi"; // default value
age: Int? = null; // optional field
point: Point; // nested structs
}
Message Sender and Throwing Errors
Message Sender
Every incoming message is sent from some contract that has an address. You can query the address of the message sender by calling sender()
deployer: Address = sender();
Errors
When an error is thrown, the transaction reverts. By writing a require() on a condition that isn't met
require(self.val < 5, "Counter is too high");
Messages Between Contracts, Sending and Receiving TON Coins
Messages Between Contracts
Different contracts can only communicate with each other by sending each other messages.
This example sends a message to the to address with value of 1 TON and body of a comment with a string "Hello, World!". SendIgnoreErrors means that even when error occurs during message sending next messages would be sent anyway.
let to: Address = ...;
let value: Int = ton("1");
send(SendParameters{
to: to, // address of receiver
value: value, // amount of TON you want to send
mode: SendIgnoreErrors, // 8-bit flag configuring how to send message
bounce: true, // if set to true (default) then message
// will be bounced back to sender
body: "Hello, World!".asComment() // message body as Cell
});
Receiving TONs
You can query the contract balance with myBalance() - note that the value is in nano-tons (like cents, just with 9 decimals). The balance already contains the incoming message value. You can also get the incoming TON balance with context().value
val: Int as int64 = myBalance()
// or
// print how much TON coin were sent with this message
dump(context().value);
Sending TONs
We can send any amount of TON to any address just like we created a send call between different contracts
Send mode SendRemainingValue will add to the outgoing value any excess left from the incoming message after all gas costs are deducted from it.
amount: Int as coins = ton("1");
send(SendParameters{
to: sender(),
bounce: true,
value: amount,
mode: SendRemainingValue + SendIgnoreErrors
});
If/Else statements and Loops
If
Tact supports if statements in a similar syntax to most programming languages. Curly braces are required. We can have the else and else if similar to other programming languages.
if (val > 1000) {
dump("larger than 1000");
} else if (val > 500) {
dump("between 500 and 1000");
} else {
dump("smaller than 500");
}
Loops
Tact does not support traditional 'for' loops, 'break' and 'continue' statements in loops. The repeat loop statement input number must fit within an int32.
// repeat exactly 10 times
repeat (10) {
i = i + 1;
sum = sum + i;
}
// While loop
let x: Int = 10;
while(x > 0) {
x = x - 1;
}
// do-until loop
let x: Int = 10;
do {
x = x - 1;
} until (x <= 0);
Functions
Functions in Tact start with the fun keyword. Functions can receive multiple input arguments and can optionally return a single output value. You can return a struct if you want to return multiple values.
fun average(a: Int, b: Int): Int {
return (a + b) / 2;
}
Maps and Arrays
Maps
Maps are a dictionary type that can hold an arbitrary number of items, each under a different key. The keys in maps can either be an Int type or an Address type. You can check if a key is found in the map by calling the get() method. Replace the value under a key by calling the set() method.
mi1: map<Int, TokenInfo>; // maps with Int as key
ma1: map<Address, TokenInfo>; // maps with Address as key
Arrays
To create an array, define a map with 'Int' type as key as well as value.
arr: map<Int, Int>; // this is our array implemented with a map
Ownable Standard Library
The Ownable trait allows the contract to set an owner role, which can have higher priviliges from everybody else. For this you would need to import the "@stdlib/ownable" library and inherit it in your contract
- Use the self.requireOwner() call to verify that the person making that function call is the owner of contract
- 'ChangeOwner{newOwner: Address}' message which allows the owner to transfer ownership.
- Define state variables named 'owner: Address' and 'stopped: Bool' and call 'self.requireNotStopped()' on actions that should be stopped.
- Define state variables named 'owner: Address' and "stopped: Bool' and call 'self.requireNotStopped()' on actions that should be stopped.
import "@stdlib/ownable";
import "@stdlib/deploy";
contract Counter with Deployable, Ownable {
owner: Address;
init() { // initialize a contract with default values like 'constructor'
self.owner = sender(); // we can initialize owner to any value we want, the deployer in this case
self.val = 0;
}
// this message in only available to the owner
receive("double") {
self.requireOwner();
self.val = self.val * 2;
}
// this message will only work until the contract was stopped
receive("increment") {
self.requireNotStopped();
self.val = self.val + 1;
}
// this message will only work as long as the contract is not stopped
receive("increment2") {
self.requireNotStopped();
self.val = self.val + 1;
}
}
Additional resources
Social
Useful blogposts
Future To Dos
- Add smart contracts examples
- Add more links to documentations
This file is based on Tact By Example.
P.S. If by any chance you're familiar with Forth, you can also take a look at Fift.