adambard/learnxinyminutes-docs
1
1
Fork 0
mirror of https://github.com/adambard/learnxinyminutes-docs.git synced 2024-11-27 04:44:08 +03:00
Code Issues Projects Releases Wiki Activity
962dfca817
learnxinyminutes-docs/tact.html.markdown
Boris Verkhovskiy 3e687f1a8c Remove leading and trailing empty lines in code blocks
2024-04-06 08:33:50 -07:00

603 lines
18 KiB
Markdown
Raw Blame History

---
language: Tact
filename: tact.tc
contributors:
- ["Tal Kol", "https://www.orbs.com/"]
- ["Kirill Malev", "https://fslabs.io"]
- ["Yash Garg", "https://github.com/yash0501"]
---
Tact language is used to program smart contracts on the
[The Open Network](https://ton.org) 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](https://tact-by-example.org/).
You can use this resource to play around with contracts and check out
the interactive features.
# Basic syntax, function definition
```c
// 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.
```c
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](https://docs.tact-lang.org/tools/typescript#tact-contract-in-typescript) TypeScript
classes to deploy, sending the deploy message should look like:
```c
const msg = { $$type: "Deploy", queryId: 0n };
await contract.send(sender, { value: toNano(1) }, msg);
```
You can see the implementation of the trait [here](https://github.com/tact-lang/tact/blob/main/stdlib/libs/deploy.tact).
Notice that the file deploy.tact needs to be imported from the standard
library using the import keyword.
```c
// 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](https://learn.microsoft.com/en-us/cpp/build/why-floating-point-numbers-may-lose-precision).
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](https://ton.org/docs/develop/smart-contracts/fees#how-to-calculate-fees) about
0.184 TON per year. Storing 1000 32-bit integers only costs
0.023 TON per year by comparison.
```c
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
```js
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.
```js
// 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.
```js
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
```js
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.
```js
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.
```js
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
```js
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)
```js
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.
```js
// 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()
```js
deployer: Address = sender();
```
### Errors
When an error is thrown, the transaction reverts. By writing a
require() on a condition that isn't met
```js
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.
```js
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
```js
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.
```js
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.
```js
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.
```js
// 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.
```js
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.
```js
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.
```js
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.
```js
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
- [TON Documentation](https://ton.org/docs/#/)
- [Tact Docs](https://docs.tact-lang.org/)
- [Tact by Example](https://tact-by-example.org/)
- [Community portal](https://society.ton.org)
- [Blockchain portal](https://ton.org)
- [Stackoverflow](https://stackoverflow.com/questions/tagged/ton)
## Social
- [Tact community](https://t.me/tactlang)
- [Developer community](https://t.me/tondev_eng)
- [TON Learn](https://t.me/ton_learn)
- [Tondev News](https://t.me/tondevnews)
- [TON Technical Updates](https://t.me/thetontech)
## Useful blogposts
- [Setting up a TON Development Environment](https://society.ton.org/setting-up-a-ton-development-environment)
- [Hello World on TON](https://society.ton.org/ton-hello-world-step-by-step-guide-for-writing-your-first-smart-contract-in-func)
## Future To Dos
- Add smart contracts examples
- Add more links to documentations
This file is based on [Tact By Example](https://tact-by-example.org).
P.S. If by any chance you're familiar with [Forth](https://learnxinyminutes.com/docs/forth/),
you can also take a look at [Fift](https://ton-blockchain.github.io/docs/fiftbase.pdf).
Reference in New Issue View Git Blame Copy Permalink