From 0a5c2ab51c8fb1fa7acb16c048836f0de5b8c42c Mon Sep 17 00:00:00 2001
From: Novus Nota <68142933+novusnota@users.noreply.github.com>
Date: Mon, 20 Jan 2025 12:49:46 +0100
Subject: [PATCH] implement suggestions from the code review

---
 docs/src/content/docs/book/contracts.mdx | 36 +++++++++++++++---------
 docs/src/content/docs/book/integers.mdx  |  9 ++++++
 2 files changed, 31 insertions(+), 14 deletions(-)

diff --git a/docs/src/content/docs/book/contracts.mdx b/docs/src/content/docs/book/contracts.mdx
index 8ba7eed5e..95bc918e4 100644
--- a/docs/src/content/docs/book/contracts.mdx
+++ b/docs/src/content/docs/book/contracts.mdx
@@ -165,6 +165,23 @@ contract Example {
 }
 ```
 
+As the contract state is updated at the very end of the [compute phase][compute] of the transaction, intermediate assignments of [`Int{:tact}`][int] values that exceed the limits specified by [serialization formats](/book/integers#serialization) won't fail immediately. Instead, such assignments would cause an [exit code 5](/book/exit-codes#5) only after all statements have been executed.
+
+This is to be expected because the integers in the temporary [TVM][tvm] memory, which is used to process the [compute phase][compute], always have $257$ bits and are capable of holding values in the inclusive range from $-2^{256}$ to $2^{256} - 1.$
+
+```tact
+contract DeRanged {
+    // Persistent state variables
+    var: Int as uint8; // cannot store values outside the 0-255 range
+
+    init() {
+        self.var = -1;  // this won't fail immediately
+        self.var = 500; // and that won't fail right away either
+    } // only here, at the end of the compute phase,
+      // would there be an error thrown with an exit code 5: Integer out of range
+}
+```
+
 :::note
 
   Tact supports local, non-persistent-state variables too, see: [Variable declaration](/book/statements#let).
@@ -217,24 +234,12 @@ contract Example {
     // persistent state variables
     var1: Int = 0; // initialized with default value 0
     var2: Int;     // must be initialized in the init() function
+    var3: Int = 7; // initialized with default value 7
 
     // constructor function
     init() {
         self.var2 = 42;
-    }
-}
-```
-
-The default value of [state variables](#variables) is assigned before any values could be assigned in the `init(){:tact}` function.
-
-```tact
-contract Example {
-    // persistent state variables
-    var1: Int = 0; // initialized with default value 0
-
-    // constructor function
-    init() {
-        self.var1 = 42; // overrides the default to 42
+        self.var3 = 32; // overrides the default to 32
     }
 }
 ```
@@ -382,7 +387,10 @@ contract Functions {
 :::
 
 [p]: /book/types#primitive-types
+[int]: /book/integers
 [trait]: /book/types#traits
 
+[compute]: https://docs.ton.org/learn/tvm-instructions/tvm-overview#compute-phase
+[tvm]: https://docs.ton.org/learn/tvm-instructions/tvm-overview
 [bp]: https://github.com/ton-org/blueprint
 [bp-config]: https://github.com/ton-org/blueprint/tree/main?tab=readme-ov-file#configuration
diff --git a/docs/src/content/docs/book/integers.mdx b/docs/src/content/docs/book/integers.mdx
index 2109ebfc4..55a5c11ed 100644
--- a/docs/src/content/docs/book/integers.mdx
+++ b/docs/src/content/docs/book/integers.mdx
@@ -89,6 +89,14 @@ Motivation is very simple:
 * Storing $1000$ $257$-bit integers in state [costs](https://docs.ton.org/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.
 
+:::note
+
+  Serialization limits apply only to the contract state between transactions and are **not** imposed on the temporary [TVM][tvm] memory, which operates only on $257$-bit integers.
+
+  Attempts to assign out-of-bounds values will result in [exit code 5](/book/exit-codes#5) being thrown at the very end of the [compute phase](https://docs.ton.org/learn/tvm-instructions/tvm-overview#compute-phase): `Integer out of range`.
+
+:::
+
 ### Common serialization types
 
 Name             | [TL-B][tlb]                 | Inclusive range             | Space taken
@@ -195,6 +203,7 @@ Here, `oneByte` is serialized as a [`uint8`](#common-serialization-types), which
   Therefore, be **very** careful with numbers and always double-check calculations when using serialization.
 :::
 
+[tvm]: https://docs.ton.org/learn/tvm-instructions/tvm-overview
 [tlb]: https://docs.ton.org/develop/data-formats/tl-b-language
 [tlb-builtin]: https://docs.ton.org/develop/data-formats/tl-b-language#built-in-types
 [varuint]: https://docs.ton.org/develop/data-formats/msg-tlb#varuinteger-n