Handling feedback over existing lessons

Author: talkol

src/routes/(examples)/01-the-deployable-trait/content.md

@@ -4,9 +4,9 @@ Tact doesn't support classical class inheritance, but contracts can implement *t
 
 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. If the deploy succeeds, the contract will reply with the message `DeployOk` and echo the same `queryId` in the response.
+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 TypeScript to deploy, sending the deploy message should look like:
+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:
 
 ```ts
 const msg = { $$type: "Deploy", queryId: 0n };

src/routes/(examples)/02-addresses/content.md

@@ -2,10 +2,14 @@
 
 `Address` is another primitive data type. It represents standard addresses on the TON blockchain. Every smart contract on TON is identifiable by its address. Think of this as a unique id.
 
-TON is divided into multiple chains called *workchains*. One of the internal fields of the address is the workchain id:
+TON is divided into multiple chains called *workchains*. This allows to balance the load more effectively. One of the internal fields of the address is the workchain id:
 
-* `0` - The standard workchain, for regular users.
+* `0` - The standard workchain, for regular users. Your contracts will be here.
 
-* `-1` - The masterchain, usually for validators.
+* `-1` - The masterchain, usually for validators. Gas on this chain is significantly more expensive, but you'll probably never use it.
 
-There are multiple ways to [represent](https://ton.org/docs/learn/overviews/addresses) the same address. Notice in the contract that the bouncable and non-bouncable representations of the same address actually generate the exact same value. It doesn't matter which representation you use.
+There are multiple ways on TON to [represent](https://docs.ton.org/learn/overviews/addresses#bounceable-vs-non-bounceable-addresses) the same address. Notice in the contract that the bouncable and non-bouncable representations of the same address actually generate the exact same value. Inside the contract, it doesn't matter which representation you use.
+
+## State costs
+
+Most addresses take 264-bit to store (8-bit for the workchain id and 256-bit for the account id). This means that storing 1000 addresses [costs](https://ton.org/docs/develop/smart-contracts/fees#how-to-calculate-fees) about 0.189 TON per year.

src/routes/(examples)/02-bools/content.md

@@ -4,4 +4,8 @@ This primitive data type can hold the values `true` or `false`.
 
 `Bool` is convenient for boolean and logical operations. It is also useful for storing flags.
 
-Persisting bools to state is very space-efficient, they only take 1 bit.
+The only supported operations with booleans are `&&` `||` `!` - if you try to add them, for example, the code will not compile.
+
+## State costs
+
+Persisting bools to state is very space-efficient, they only take 1-bit. Storing 1000 bools in state [costs](https://ton.org/docs/develop/smart-contracts/fees#how-to-calculate-fees) about 0.00072 TON per year.

src/routes/(examples)/02-constants/content.md

@@ -6,4 +6,6 @@ Constant initializations must be relatively simple and only rely on values known
 
 You can read constants both in *receivers* and in *getters*.
 
-Unlike contract variables, constants don't consume space in persistent state. Their values are stored directly in the code cell.
+Unlike contract variables, constants don't consume space in persistent state. Their values are stored directly in the code cell.
+
+There isn't much difference between constants defined outside of a contract and inside the contract. Those defined outside can be used by other contracts in your project.

src/routes/(examples)/02-integer-ops/content.md

@@ -1,7 +1,13 @@
 # Integer Operations
 
-Since all runtime calculations with integers are done at 257-bit, overflows are quite rare.
+Since all runtime calculations with integers are done at 257-bit, overflows are quite rare. An overflow can happen if the result of a math operation is too big to fit. For example, multiplying 2^256 by 2^256 will not fit within 257-bit.
 
-Nevertheless, if any math operation overflows, an exception will be thrown and the transaction will revert. You can say that Tact's math is safe by default.
+Nevertheless, if any math operation overflows, an exception will be thrown and the transaction will fail. You can say that Tact's math is safe by default.
 
-There's no problem with mixing variables of different state sizes in the same calculation. In runtime, they are all the same type - always 257-bit signed. This is the largest supported integer type, so they all fit.
+There's no problem with mixing variables of different state sizes in the same calculation. In runtime, they are all the same type - always 257-bit signed. This is the largest supported integer type, so they all fit.
+
+## Decimal point with integers
+
+Arithmetics with dollars, for example, requires 2 decimal places. How can we represent the number `1.25` if we can only work with integers? The answer is to work with *cents*. So `1.25` becomes `125`. We just remember that the two lowest digits are coming after the decimal point.
+
+In the same way, working with TON coins has 9 decimal places instead of 2. So the amount 1.25 TON which can be coded in Tact as `ton("1.25")` is actually the number `1250000000` - we call these *nano-tons* instead of cents.

src/routes/(examples)/02-integer-ops/contract.tact

@@ -15,10 +15,10 @@ contract Integers with Deployable {
         i = self.i1 * 3 + (self.i2 - i);    // basic math expressions
         dump(i);
 
-        i = self.i1 % 10;                   // modulo (remainder after division)
+        i = self.i1 % 10;                   // modulo (remainder after division), 3001 % 10 = 1
         dump(i);
 
-        i = self.i1 / 1000;                 // integer division (truncation toward zero)
+        i = self.i1 / 1000;                 // integer division (truncation toward zero), 3001 / 1000 = 3
         dump(i);
 
         i = self.i1 >> 3;                   // shift right (multiply by 2^n)

src/routes/(examples)/02-integers/content.md

@@ -2,10 +2,14 @@
 
 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 no floating points.
+`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 enough for everything as it's large enough to hold the number of atoms in the universe.
+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.
 
-Persistent state variables can be initialized inline or inside `init()`. If you forget to initialize a state variable, the code will not compile.
+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.

src/routes/(examples)/02-integers/contract.tact

@@ -20,8 +20,8 @@ contract Integers with Deployable {
     i14: Int as int8 = 0;       // range -128 to 127 (takes 8 bit = 1 byte)
 
     init() {
-        self.i2 = 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8;
-        self.i4 = 1507998500293440234999;
+        self.i2 = 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8; // we can define numbers in hex (base 16)
+        self.i4 = 1507998500293440234999; // we can define numbers in decimal (base 10)
         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)
     }

src/routes/(examples)/02-strings/content.md

@@ -1,7 +1,9 @@
 # Strings
 
-Tact has basic support for strings. Strings support unicode and don't have any special escape characters like `\n`. The use of strings in smart contracts should be quite limited.
+Tact has basic support for strings. Strings support unicode and don't have any special escape characters like `\n`.
+
+The use of strings in smart contracts should be quite limited. Smart contracts are very exact programs for managing money, they're not intended for interactive CLI.
 
 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.
+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.

src/routes/(examples)/03-receivers/content.md

@@ -4,12 +4,12 @@ In TON, users interact with contracts by sending them messages. Different contra
 
 Since users actually use wallet contracts, messages from users are actually messages coming from just another contract.
 
-Sending a message to a contract costs gas and is processed in the course of a transaction. The transaction executes when validators add the transaction to a new block. This can take a few seconds. Messages are also able to change the contract persistent state.
+Sending a message to a contract costs gas and is processed in the course of a transaction. The transaction executes when validators add the transaction to a new block. This can take a few seconds. Messages are also able to change the contract's persistent state.
 
 ## Receivers
 
 When designing your contract, make a list of every operation that your contract supports, then, define a message for each operation, and finally, implement a handler for each message containing the logic of what to do when it arrives.
 
-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.
+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.
 
 Messages are defined using the `message` keyword. They can carry input arguments. Notice that for integers, you must define the encoding size, just like in state variables. When somebody sends the message, they serialize it over the wire.