mirror of
https://github.com/adambard/learnxinyminutes-docs.git
synced 2024-12-23 17:41:41 +00:00
Update Tact doc with all examples
This commit is contained in:
parent
fe3d3fd1ef
commit
e5d4bb7933
@ -4,6 +4,7 @@ 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
|
||||
@ -39,8 +40,8 @@ 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.
|
||||
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.
|
||||
@ -72,17 +73,17 @@ 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;
|
||||
@ -97,7 +98,7 @@ 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`
|
||||
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
|
||||
@ -122,17 +123,17 @@ 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;
|
||||
}
|
||||
@ -161,7 +162,7 @@ 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
|
||||
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.
|
||||
|
||||
@ -169,26 +170,26 @@ Storing 1000 257-bit integers in state [costs](https://ton.org/docs/develop/smar
|
||||
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;
|
||||
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;
|
||||
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;
|
||||
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;
|
||||
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;
|
||||
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)
|
||||
@ -196,7 +197,7 @@ contract Integers with Deployable {
|
||||
|
||||
init() {
|
||||
// we can define numbers in hex (base 16)
|
||||
self.i2 = 0x83dfd552e6372;
|
||||
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
|
||||
@ -220,19 +221,371 @@ contract Integers with Deployable {
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
@ -244,7 +597,7 @@ contract Integers with Deployable {
|
||||
- Add smart contracts examples
|
||||
- Add more links to documentations
|
||||
|
||||
This file is based on [Tact By Example](https://tact-by-example.org/04-decimal-point).
|
||||
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).
|
||||
|
Loading…
Reference in New Issue
Block a user