feat(docs): add a real-world example for the commit() function in the Reference and the Cookbook (#3370)

Author: novusnota

docs/src/content/docs/cookbook/single-communication.mdx

@@ -120,6 +120,48 @@ contract Example {
 
 :::
 
+## How to commit the state for the sequence number
+
+To prevent the possibility of replay attacks, you can use unique identifiers, such as `seqno`. Yet, the changes made to it must persist. To do so, the [`commit(){:tact}`](/ref/core-contextstate#commit) function is used.
+
+```tact {20}
+message MsgWithSignedData {
+    bundle: SignedBundle;
+    seqno: Int as uint64;
+    someExtraData: Cell;
+}
+
+contract Sample(
+    publicKey: Int as uint256,
+    seqno: Int as uint64,
+) {
+    external(msg: MsgWithSignedData) {
+        // Various checks with accepting the external message processing afterwards
+        require(msg.bundle.verifySignature(self.publicKey), "Invalid signature");
+        require(msg.seqno == self.seqno, "Invalid seqno");
+        acceptMessage();
+
+        // Since we have done all the checks we can now safely increase the number,
+        // then commit the state of persistent data and output actions,
+        // and, finally, save that state early, before any further actions take place.
+        self.seqno += 1;
+        commit();
+        setData(self.toCell());
+
+        // And now you can safely do something with the rest of the message,
+        // knowing that the `self.seqno` change will not be reverted in case of errors
+        throw(42); // this will prevent subsequent code from executing,
+        //            but will not fail the transaction!
+    }
+
+    // Empty receiver for the deployment,
+    // which forwards the remaining value back to the sender
+    receive() { cashback(sender()) }
+}
+
+asm fun setData(data: Cell) { c4 POP }
+```
+
 :::tip[Hey there!]
 
   Didn't find your favorite example of single-contract communication? Have cool implementations in mind? [Contributions are welcome!](https://github.com/tact-lang/tact/issues)

docs/src/content/docs/ref/core-contextstate.mdx

@@ -372,9 +372,24 @@ Commits the current state of [registers][registers] `c4` (persistent data) and `
 
 Usage example:
 
-```tact {1}
-commit();  // now, transaction is considered "successful"
-throw(42); // and this won't fail it
+```tact {12}
+contract WalletV4(
+    seqno: Int as uint32,
+    // ...other parameters...
+) {
+    // ...
+    external(_: Slice) {
+        // ...various prior checks...
+
+        acceptMessage();
+        self.seqno += 1;
+        setData(self.toCell());
+        commit(); //  now, transaction is considered "successful"
+        throw(42); // and this won't fail it
+    }
+}
+
+asm fun setData(data: Cell) { c4 POP }
 ```
 
 ## Blockchain state

src/stdlib/stdlib.ts

@@ -1915,10 +1915,14 @@ files["std/internal/send.tact"] =
     "Ly8vICAgICB9Ci8vLyB9Ci8vLyBgYGAKLy8vCi8vLyBTZWU6IGh0dHBzOi8vZG9jcy50YWN0LWxhbmcub3JnL3JlZi9jb3JlLWdhcyNhY2NlcHRtZXNzYWdlCi8vLwph" +
     "c20gZnVuIGFjY2VwdE1lc3NhZ2UoKSB7IEFDQ0VQVCB9CgovLy8gR2xvYmFsIGZ1bmN0aW9uLgovLy8KLy8vIENvbW1pdHMgdGhlIGN1cnJlbnQgc3RhdGUgb2YgcmVn" +
     "aXN0ZXJzIGBjNGAgKHBlcnNpc3RlbnQgZGF0YSkgYW5kIGBjNWAgKGFjdGlvbnMpLCBzbyB0aGF0IHRoZSBjdXJyZW50IGV4ZWN1dGlvbiBpcyBjb25zaWRlcmVkICJz" +
-    "dWNjZXNzZnVsIiB3aXRoIHRoZSBzYXZlZCB2YWx1ZXMgZXZlbiBpZiBhbiBleGNlcHRpb24gaW4gY29tcHV0ZSBwaGFzZSBpcyB0aHJvd24gbGF0ZXIuCi8vCi8vLyBg" +
-    "YGB0YWN0Ci8vLyBmdW4gZXhhbXBsZSgpIHsKLy8vICAgICBjb21taXQoKTsgIC8vIG5vdywgdHJhbnNhY3Rpb24gaXMgY29uc2lkZXJlZCAic3VjY2Vzc2Z1bCIKLy8v" +
-    "ICAgICB0aHJvdyg0Mik7IC8vIGFuZCB0aGlzIHdvbid0IGZhaWwgaXQKLy8vIH0KLy8vIGBgYAovLy8KLy8vIFNlZTogaHR0cHM6Ly9kb2NzLnRhY3QtbGFuZy5vcmcv" +
-    "cmVmL2NvcmUtY29udGV4dHN0YXRlI2NvbW1pdAovLy8KYXNtIGZ1biBjb21taXQoKSB7IENPTU1JVCB9Cg==";
+    "dWNjZXNzZnVsIiB3aXRoIHRoZSBzYXZlZCB2YWx1ZXMgZXZlbiBpZiBhbiBleGNlcHRpb24gaW4gY29tcHV0ZSBwaGFzZSBpcyB0aHJvd24gbGF0ZXIuCi8vLwovLy8g" +
+    "YGBgdGFjdAovLy8gY29udHJhY3QgV2FsbGV0VjQoCi8vLyAgICAgc2Vxbm86IEludCBhcyB1aW50MzIsCi8vLyAgICAgLy8gLi4ub3RoZXIgcGFyYW1ldGVycy4uLgov" +
+    "Ly8gKSB7Ci8vLyAgICAgLy8gLi4uCi8vLyAgICAgZXh0ZXJuYWwoXzogU2xpY2UpIHsKLy8vICAgICAgICAgLy8gLi4udmFyaW91cyBwcmlvciBjaGVja3MuLi4KLy8v" +
+    "Ci8vLyAgICAgICAgIGFjY2VwdE1lc3NhZ2UoKTsKLy8vICAgICAgICAgc2VsZi5zZXFubyArPSAxOwovLy8gICAgICAgICBzZXREYXRhKHNlbGYudG9DZWxsKCkpOwov" +
+    "Ly8gICAgICAgICBjb21taXQoKTsgLy8gIG5vdywgdHJhbnNhY3Rpb24gaXMgY29uc2lkZXJlZCAic3VjY2Vzc2Z1bCIKLy8vICAgICAgICAgdGhyb3coNDIpOyAvLyBh" +
+    "bmQgdGhpcyB3b24ndCBmYWlsIGl0Ci8vLyAgICAgfQovLy8gfQovLy8KLy8vIGFzbSBmdW4gc2V0RGF0YShkYXRhOiBDZWxsKSB7IGM0IFBPUCB9Ci8vLyBgYGAKLy8v" +
+    "Ci8vLyBTZWU6IGh0dHBzOi8vZG9jcy50YWN0LWxhbmcub3JnL3JlZi9jb3JlLWNvbnRleHRzdGF0ZSNjb21taXQKLy8vCmFzbSBmdW4gY29tbWl0KCkgeyBDT01NSVQg" +
+    "fQo=";
 files["std/internal/text.tact"] =
     "Ly8KLy8gU3RyaW5nIGJ1aWxkZXIKLy8KCi8vLyBHbG9iYWwgZnVuY3Rpb24uCi8vLwovLy8gQ3JlYXRlcyBhbmQgcmV0dXJucyBhbiBlbXB0eSBgU3RyaW5nQnVpbGRl" +
     "cmAuCi8vLwovLy8gYGBgdGFjdAovLy8gZnVuIGV4YW1wbGUoKTogU3RyaW5nIHsKLy8vICAgICBsZXQgZml6ejogU3RyaW5nQnVpbGRlciA9IGJlZ2luU3RyaW5nKCk7" +

src/stdlib/stdlib/std/internal/send.tact

@@ -610,12 +610,25 @@ asm fun acceptMessage() { ACCEPT }
 /// Global function.
 ///
 /// Commits the current state of registers `c4` (persistent data) and `c5` (actions), so that the current execution is considered "successful" with the saved values even if an exception in compute phase is thrown later.
-//
+///
 /// ```tact
-/// fun example() {
-///     commit();  // now, transaction is considered "successful"
-///     throw(42); // and this won't fail it
+/// contract WalletV4(
+///     seqno: Int as uint32,
+///     // ...other parameters...
+/// ) {
+///     // ...
+///     external(_: Slice) {
+///         // ...various prior checks...
+///
+///         acceptMessage();
+///         self.seqno += 1;
+///         setData(self.toCell());
+///         commit(); //  now, transaction is considered "successful"
+///         throw(42); // and this won't fail it
+///     }
 /// }
+///
+/// asm fun setData(data: Cell) { c4 POP }
 /// ```
 ///
 /// See: https://docs.tact-lang.org/ref/core-contextstate#commit