feat(docs): explain that contracts return excess funds upon deployments with Deployable trait (#3398)

Author: novusnota

docs/src/content/docs/ref/stdlib-deploy.mdx

@@ -61,7 +61,9 @@ The trait `Deployable{:tact}` provides a unified mechanism for deployments by im
 
 All contracts are deployed by sending them a message. While any message can be used for this purpose, you can use the special [`Deploy{:tact}`](#deploy) message.
 
-This message has a single field, `queryId`, provided by the deployer (usually set to zero). If the deployment succeeds, the contract will reply with a [`DeployOk{:tact}`](#deployok) message and echo the same `queryId` in the response.
+This message has a single field, `queryId`, provided by the deployer and is usually set to zero. If the deployment succeeds, the contract will reply with a [`DeployOk{:tact}`](#deployok) message and echo the same `queryId` in the response.
+
+Beware that the receiver handling the `Deploy{:tact}` message sends the `DeployOk{:tact}` reply using the [`self.reply(){:tact}`](/ref/core-base#self-reply) function, which returns all excessive funds from the incoming message back to the sender. That is, contracts deployed using the `Deployable{:tact}` trait have a balance of 0 Toncoin after the deployment is completed.
 
 Source code:
 

src/stdlib/stdlib.ts

@@ -28,20 +28,23 @@ files["libs/deploy.tact"] =
     "bWVjaGFuaXNtIGZvciBkZXBsb3ltZW50cyBieSBpbXBsZW1lbnRpbmcgYQovLy8gc2ltcGxlIHJlY2VpdmVyIGZvciB0aGUgYERlcGxveWAgbWVzc2FnZS4KLy8vCi8v" +
     "LyBBbGwgY29udHJhY3RzIGFyZSBkZXBsb3llZCBieSBzZW5kaW5nIHRoZW0gYSBtZXNzYWdlLiBXaGlsZSBhbnkgbWVzc2FnZQovLy8gY2FuIGJlIHVzZWQgZm9yIHRo" +
     "aXMgcHVycG9zZSwgdGhlIGJlc3QgcHJhY3RpY2UgaXMgdG8gdXNlIHRoZSBzcGVjaWFsCi8vLyBgRGVwbG95YCBtZXNzYWdlLgovLy8KLy8vIFRoaXMgbWVzc2FnZSBo" +
-    "YXMgYSBzaW5nbGUgZmllbGQsIGBxdWVyeUlkYCwgcHJvdmlkZWQgYnkgdGhlIGRlcGxveWVyCi8vLyAodXN1YWxseSBzZXQgdG8gemVybykuIElmIHRoZSBkZXBsb3lt" +
-    "ZW50IHN1Y2NlZWRzLCB0aGUgY29udHJhY3Qgd2lsbAovLy8gcmVwbHkgd2l0aCBhIGBEZXBsb3lPa2AgbWVzc2FnZSBhbmQgZWNobyB0aGUgc2FtZSBgcXVlcnlJZGAg" +
-    "aW4gdGhlIHJlc3BvbnNlLgovLy8KLy8vIGBgYHRhY3QKLy8vIGltcG9ydCAiQHN0ZGxpYi9kZXBsb3kiOwovLy8KLy8vIGNvbnRyYWN0IEV4YW1wbGVDb250cmFjdCB3" +
-    "aXRoIERlcGxveWFibGUgewovLy8gICAgIC8vIE5vdywgdGhpcyBjb250cmFjdCBoYXMgYSByZWNlaXZlciBmb3IgdGhlIERlcGxveSBtZXNzYWdlCi8vLyB9Ci8vLyBg" +
-    "YGAKLy8vCi8vLyBTZWU6IGh0dHBzOi8vZG9jcy50YWN0LWxhbmcub3JnL3JlZi9zdGRsaWItZGVwbG95I2RlcGxveWFibGUKLy8vCnRyYWl0IERlcGxveWFibGUgd2l0" +
-    "aCBCYXNlVHJhaXQgewogICAgcmVjZWl2ZShkZXBsb3k6IERlcGxveSkgewogICAgICAgIHNlbGYubm90aWZ5KERlcGxveU9rIHsgcXVlcnlJZDogZGVwbG95LnF1ZXJ5" +
-    "SWQgfS50b0NlbGwoKSk7CiAgICB9Cn0KCi8vLyAqKkRlcHJlY2F0ZWQqKiBzaW5jZSBUYWN0IDEuNi4wLiBVbmxlc3MgeW91IG5lZWQgdGhlIGBxdWVyeUlkYCwKLy8v" +
-    "IHVzZSBhIGBudWxsYCBtZXNzYWdlIGJvZHkgcmVjZWl2ZXIgaW5zdGVhZCBvZiB0aGlzIHRyYWl0LgovLy8KLy8vIFByb3ZpZGVzIGEgY29udmVuaWVudCB1bmlmaWVk" +
-    "IG1lY2hhbmlzbSBmb3IgY2hhaW5lZCBkZXBsb3ltZW50cy4KLy8vCi8vLyBgYGB0YWN0Ci8vLyBpbXBvcnQgIkBzdGRsaWIvZGVwbG95IjsKLy8vCi8vLyBjb250cmFj" +
-    "dCBFeGFtcGxlQ29udHJhY3Qgd2l0aCBGYWN0b3J5RGVwbG95YWJsZSB7Ci8vLyAgICAgLy8gTm93LCB0aGlzIGNvbnRyYWN0IGhhcyBhIHJlY2VpdmVyIGZvciB0aGUg" +
-    "RmFjdG9yeURlcGxveSBtZXNzYWdlCi8vLyB9Ci8vLyBgYGAKLy8vCi8vLyBTZWU6IGh0dHBzOi8vZG9jcy50YWN0LWxhbmcub3JnL3JlZi9zdGRsaWItZGVwbG95I2Zh" +
-    "Y3RvcnlkZXBsb3lhYmxlCi8vLwp0cmFpdCBGYWN0b3J5RGVwbG95YWJsZSB3aXRoIEJhc2VUcmFpdCB7CiAgICByZWNlaXZlKGRlcGxveTogRmFjdG9yeURlcGxveSkg" +
-    "ewogICAgICAgIHNlbGYuZm9yd2FyZChkZXBsb3kuY2FzaGJhY2ssIERlcGxveU9rIHsgcXVlcnlJZDogZGVwbG95LnF1ZXJ5SWQgfS50b0NlbGwoKSwgZmFsc2UsIG51" +
-    "bGwpOwogICAgfQp9Cg==";
+    "YXMgYSBzaW5nbGUgZmllbGQsIGBxdWVyeUlkYCwgcHJvdmlkZWQgYnkgdGhlIGRlcGxveWVyCi8vLyBhbmQgaXMgdXN1YWxseSBzZXQgdG8gemVyby4gSWYgdGhlIGRl" +
+    "cGxveW1lbnQgc3VjY2VlZHMsIHRoZSBjb250cmFjdCB3aWxsCi8vLyByZXBseSB3aXRoIGEgYERlcGxveU9rYCBtZXNzYWdlIGFuZCBlY2hvIHRoZSBzYW1lIGBxdWVy" +
+    "eUlkYCBpbiB0aGUgcmVzcG9uc2UuCi8vLwovLy8gQmV3YXJlIHRoYXQgdGhlIHJlY2VpdmVyIGhhbmRsaW5nIHRoZSBgRGVwbG95YCBtZXNzYWdlIHNlbmRzIHRoZSBg" +
+    "RGVwbG95T2tgIHJlcGx5Ci8vLyB1c2luZyB0aGUgYHNlbGYucmVwbHkoKWAgZnVuY3Rpb24sIHdoaWNoIHJldHVybnMgYWxsIGV4Y2Vzc2l2ZSBmdW5kcwovLy8gZnJv" +
+    "bSB0aGUgaW5jb21pbmcgbWVzc2FnZSBiYWNrIHRvIHRoZSBzZW5kZXIuIFRoYXQgaXMsIGNvbnRyYWN0cyBkZXBsb3llZAovLy8gdXNpbmcgdGhlIGBEZXBsb3lhYmxl" +
+    "YCB0cmFpdCBoYXZlIGEgYmFsYW5jZSBvZiAwIFRvbmNvaW4KLy8vIGFmdGVyIHRoZSBkZXBsb3ltZW50IGlzIGNvbXBsZXRlZC4KLy8vCi8vLyBgYGB0YWN0Ci8vLyBp" +
+    "bXBvcnQgIkBzdGRsaWIvZGVwbG95IjsKLy8vCi8vLyBjb250cmFjdCBFeGFtcGxlQ29udHJhY3Qgd2l0aCBEZXBsb3lhYmxlIHsKLy8vICAgICAvLyBOb3csIHRoaXMg" +
+    "Y29udHJhY3QgaGFzIGEgcmVjZWl2ZXIgZm9yIHRoZSBEZXBsb3kgbWVzc2FnZQovLy8gfQovLy8gYGBgCi8vLwovLy8gU2VlOiBodHRwczovL2RvY3MudGFjdC1sYW5n" +
+    "Lm9yZy9yZWYvc3RkbGliLWRlcGxveSNkZXBsb3lhYmxlCi8vLwp0cmFpdCBEZXBsb3lhYmxlIHdpdGggQmFzZVRyYWl0IHsKICAgIHJlY2VpdmUoZGVwbG95OiBEZXBs" +
+    "b3kpIHsKICAgICAgICBzZWxmLm5vdGlmeShEZXBsb3lPayB7IHF1ZXJ5SWQ6IGRlcGxveS5xdWVyeUlkIH0udG9DZWxsKCkpOwogICAgfQp9CgovLy8gKipEZXByZWNh" +
+    "dGVkKiogc2luY2UgVGFjdCAxLjYuMC4gVW5sZXNzIHlvdSBuZWVkIHRoZSBgcXVlcnlJZGAsCi8vLyB1c2UgYSBgbnVsbGAgbWVzc2FnZSBib2R5IHJlY2VpdmVyIGlu" +
+    "c3RlYWQgb2YgdGhpcyB0cmFpdC4KLy8vCi8vLyBQcm92aWRlcyBhIGNvbnZlbmllbnQgdW5pZmllZCBtZWNoYW5pc20gZm9yIGNoYWluZWQgZGVwbG95bWVudHMuCi8v" +
+    "LwovLy8gYGBgdGFjdAovLy8gaW1wb3J0ICJAc3RkbGliL2RlcGxveSI7Ci8vLwovLy8gY29udHJhY3QgRXhhbXBsZUNvbnRyYWN0IHdpdGggRmFjdG9yeURlcGxveWFi" +
+    "bGUgewovLy8gICAgIC8vIE5vdywgdGhpcyBjb250cmFjdCBoYXMgYSByZWNlaXZlciBmb3IgdGhlIEZhY3RvcnlEZXBsb3kgbWVzc2FnZQovLy8gfQovLy8gYGBgCi8v" +
+    "LwovLy8gU2VlOiBodHRwczovL2RvY3MudGFjdC1sYW5nLm9yZy9yZWYvc3RkbGliLWRlcGxveSNmYWN0b3J5ZGVwbG95YWJsZQovLy8KdHJhaXQgRmFjdG9yeURlcGxv" +
+    "eWFibGUgd2l0aCBCYXNlVHJhaXQgewogICAgcmVjZWl2ZShkZXBsb3k6IEZhY3RvcnlEZXBsb3kpIHsKICAgICAgICBzZWxmLmZvcndhcmQoZGVwbG95LmNhc2hiYWNr" +
+    "LCBEZXBsb3lPayB7IHF1ZXJ5SWQ6IGRlcGxveS5xdWVyeUlkIH0udG9DZWxsKCksIGZhbHNlLCBudWxsKTsKICAgIH0KfQo=";
 files["libs/dns.fc"] =
     "c2xpY2UgZG5zX3N0cmluZ190b19pbnRlcm5hbChzbGljZSBkb21haW4pIGlubGluZV9yZWYgewoKICAgIDs7IFNwZWNpYWwgY2FzZSBmb3Igcm9vdCBkb21haW4KICAg" +
     "IGlmICgoZG9tYWluLnNsaWNlX2JpdHMoKSA9PSA4KSAmIChkb21haW4uc2xpY2VfcmVmcygpID09IDApKSB7CiAgICAgICAgaWYgKGRvbWFpbi5wcmVsb2FkX3VpbnQo" +

src/stdlib/stdlib/libs/deploy.tact

@@ -40,9 +40,15 @@ message(0x6d0ff13b) FactoryDeploy {
 /// `Deploy` message.
 ///
 /// This message has a single field, `queryId`, provided by the deployer
-/// (usually set to zero). If the deployment succeeds, the contract will
+/// and is usually set to zero. If the deployment succeeds, the contract will
 /// reply with a `DeployOk` message and echo the same `queryId` in the response.
 ///
+/// Beware that the receiver handling the `Deploy` message sends the `DeployOk` reply
+/// using the `self.reply()` function, which returns all excessive funds
+/// from the incoming message back to the sender. That is, contracts deployed
+/// using the `Deployable` trait have a balance of 0 Toncoin
+/// after the deployment is completed.
+///
 /// ```tact
 /// import "@stdlib/deploy";
 ///