From 8ce47ce358153b3d29070046146814768dbaccb0 Mon Sep 17 00:00:00 2001 From: "DanIsNearby.eth" <91475837+DanIsNearby@users.noreply.github.com> Date: Sun, 28 Jan 2024 06:38:35 +0100 Subject: [PATCH] Refine grammar and style in the documentation's language section. (#39) Co-authored-by: Anton Trunov --- pages/language/guides/bounced.mdx | 6 +-- pages/language/guides/changelog.mdx | 64 +++++++++++++------------- pages/language/guides/config.mdx | 6 +-- pages/language/guides/constants.mdx | 10 ++-- pages/language/guides/debug.mdx | 16 +++---- pages/language/guides/deploy.mdx | 10 ++-- pages/language/guides/external.mdx | 8 ++-- pages/language/guides/func.mdx | 20 ++++---- pages/language/guides/functions.mdx | 18 ++++---- pages/language/guides/lifecycle.mdx | 14 +++--- pages/language/guides/masterchain.mdx | 10 ++-- pages/language/guides/programmatic.mdx | 6 +-- pages/language/guides/receive.mdx | 6 +-- pages/language/guides/send.mdx | 20 ++++---- pages/language/guides/statements.mdx | 14 +++--- pages/language/guides/types.mdx | 20 ++++---- pages/language/guides/upgrades.mdx | 2 +- 17 files changed, 125 insertions(+), 125 deletions(-) diff --git a/pages/language/guides/bounced.mdx b/pages/language/guides/bounced.mdx index 7b384588..9a8c0924 100644 --- a/pages/language/guides/bounced.mdx +++ b/pages/language/guides/bounced.mdx @@ -2,11 +2,11 @@ import { Callout } from 'nextra-theme-docs' # Bounced messages -When contract sends a message with a flag bounce set to true, than if the message wasn't processed properly, it would bounce back to the sender. This is useful when you want to make sure that the message was processed properly and if not - revert the changes. +When a contract sends a message with a flag bounce set to true, then if the message wasn't processed properly, it would bounce back to the sender. This is useful when you want to make sure that the message was processed properly and if not - revert the changes. ## Caveats -Currently in TON bounced messages have only 224 usable data bits in the message and no references. This means that you can't recover much of a data from the bounced message. This is a limitation of the TON blockchain and will be fixed in the future. Tact helps you to check if your message fits the limit and if not - it will suggest to use a special type modifier `bounced` for receiver that would construct a partial representation that fits into required limits. +Currently in TON bounced messages have only 224 usable data bits in the message and no references. This means that you can't recover much of the data from the bounced message. This is a limitation of the TON blockchain and will be fixed in the future. Tact helps you to check if your message fits the limit and if not - it will suggest to use a special type modifier `bounced` for the receiver that would construct a partial representation that fits into the required limits. ## Bounced messages in Tact @@ -24,7 +24,7 @@ contract MyContract { } ``` -To process bounced message manually, you can use a fallback definition that handles raw `Slice` instead of a message: +To process bounced messages manually, you can use a fallback definition that handles raw `Slice` instead of a message: ```tact contract MyContract { diff --git a/pages/language/guides/changelog.mdx b/pages/language/guides/changelog.mdx index b1e3e387..8dcdbc8f 100644 --- a/pages/language/guides/changelog.mdx +++ b/pages/language/guides/changelog.mdx @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- bitwise and and or operations +- bitwise 'and' and 'or' operations - statically compile expressions with bitwise operations if possible ## [1.1.2] - 2023-04-28 @@ -29,9 +29,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### ⚡️ Breaking changes -- `reply` is now a method of `Contract` instead of global context and changed it's behaviour if storage reserve is non-zero in contract. -- Logical expressions are now calculated differently: `&&` now does not execute right expression if left is `false` and `||` does not execute right expression if left is `true`. Before it was executed in any case. This change is made in attempt to reduce unexpected behaviour. -- `OwnableTransferable` is now sends response to the sender. +- `reply` is now a method of `Contract` instead of global context and changed its behavior if the storage reserve is non-zero in the contract. +- Logical expressions are now calculated differently: `&&` now does not execute the right expression if the left is `false` and `||` does not execute the right expression if the left is `true`. Before it was executed in any case. This change is made in an attempt to reduce unexpected behavior. +- `OwnableTransferable` now sends a response to the sender. - `overwrites` was renamed to `override` - `Deployable` trait now sends non-bounceable notifications instead of bounceable ones. @@ -40,7 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - `Address` to `Address` maps - Ability to define key and value serializations for maps - `sha256` hashing -- `forward` and `notify` functions that can be used to send messages to other contracts using remaining value of incoming message +- `forward` and `notify` functions that can be used to send messages to other contracts using the remaining value of the incoming message - `virtual` and `abstract` constants that can be shared between traits - `storageReserve` constant in every contract that can be used to reserve some storage space by any trait - `abstract` functions that can be implemented in contracts @@ -62,7 +62,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- `sender()` function to get message sender address +- `sender()` function to get the message sender address - `pow` function for exponentiation - `address()` compile-time function for creating addresses from strings - `cell()` compile-time function for creating cells from base64 strings @@ -70,14 +70,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - report workchain support in interfaces - exported `check` function for language server support - `logger` interface to programmatic API -- `verify` function to verify compiled package +- `verify` function to verify the compiled package ### Changed - Upgrade `func` to `0.4.2` - Contracts now work only with basic workchain. To enable masterchain support set `masterchain: true` in `tact.conf.json` - Contracts now can be deployed only to the basic workchain unless `masterchain` set `true` -- Checking field initialization in init function +- Checking field initialization in the init function ### Fixed @@ -85,7 +85,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Removed -- Removed jetton library from stdlib. It would be re-introduced after 1.0 version with more thought put into it. +- Removed Jetton library from stdlib. It would be re-introduced after the 1.0 version with more thought put into it. ## [0.10.1] - 2023-02-23 @@ -102,19 +102,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Changed -- Tact contracts are now [Argument-addressable](https://docs.tact-lang.org/evolution/OTP-005) meaning that they depend on init arguments and code hash only. Init function is now called when first valid message is received. +- Tact contracts are now [Argument-addressable](https://docs.tact-lang.org/evolution/OTP-005) meaning that they depend on init arguments and code hash only. The init function is now called when the first valid message is received. - Refactoring of allocator -- Moving contract's load function to the beginning of the execution -- Moving contract's save function to the end of the execution -- moving `debug` flag from `experimental` to `parameters` in `tact.config.json` -- Unknown fields in config are now considered an error +- Moving the contract's load function to the beginning of the execution +- Moving the contract's save function to the end of the execution +- moving the `debug` flag from `experimental` to `parameters` in `tact.config.json` +- Unknown fields in the config are now considered an error - Allow contracts without fields -- Typescript bindings are now working in browser and doesn't have `ton-emulator` dependency +- Typescript bindings are now working in the browser and don't have `ton-emulator` dependency - `map` syntax now uses `<>` instead of `[]` for future compatibility with generics ### Added -- Allow `Builder` type as a field type similar to `Cell` and `Slice` +- Allow the `Builder` type as a field type similar to `Cell` and `Slice` - Allow `String` type as a field type ## [0.9.3] - 2023-02-19 @@ -133,13 +133,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - `emptyMap()` for creating empty maps -- Allowing assigning `null` value to a map variable (same as calling `emptyMap()`) +- Allowing assigning the `null` value to a map variable (same as calling `emptyMap()`) ## [0.9.1] - 2023-02-03 ### Changed -- Update `dump` function to handle booleans and strings, better type checking or arguments +- Update the `dump` function to handle booleans and strings, better type checking or arguments - Report `org.ton.debug.v0` interface if debug mode is enabled - Update bindings generator to support `ton-emulator >= v2.1.0` @@ -241,12 +241,12 @@ Fixing missing NPM release ### Changed -- Changed message id algorithm to the one based on type signatures instead of tlb +- Changed message ID algorithm to the one based on type signatures instead of TLB ### Added - Dictionaries in typescript bindings -- Introduced packaging compilation step that packages a contract to a single package that can be deployed in predictable way. +- Introduced a packaging compilation step that packages a contract to a single package that can be deployed predictably. - `tact-bindings` to build bindings to non-tact contracts ## [0.7.1] - 2023-01-04 @@ -269,8 +269,8 @@ Fixing missing NPM release ### Changed -- Updated codegen to prefix function names with a `$` to avoid clashing with system functions -- `random` and `randomInt` that are correctly initialized on first use unlike native one +- Updated code generation to prefix function names with a `$` to avoid clashing with system functions +- `random` and `randomInt` that are correctly initialized on first use unlike the native one - Changed the way get and init methods expect their arguments and return values to match func-like primitives ### Fixed @@ -299,7 +299,7 @@ Fixing missing NPM release ### Changed -- `require` now accepts two arguments, second one must be a string literal that has error message. This error message then will be exported to ABI +- `require` now accepts two arguments: the second one must be a string literal that has an error message. This error message then will be exported to ABI - Optional `Address` fields are not encoded using native representation ## [0.4.0] - 2022-12-22 @@ -319,23 +319,23 @@ Fixing missing NPM release - `String` literals and variables - `Int.toString()` and `Int.toFloatString()` - `StringBuilder` for gas-efficient string building -- Global compile-time `ton` function that converts string to Int during compile time. +- Global compile-time `ton` function that converts a string to `Int` during compile time. - `checkDataSignature` similar to func `check_data_signature` - `String.asComment` for conversion text to a comment payload -- `Resumable` trait, allows to resume contract operations once it was stopped +- `Resumable` trait, allows to resume operations, once the contract was stopped - Comment receiver that allows to receive arbitrary comment - `String.asSlice` cast string to a slice for parsing - Binary shift operators `>>` and `<<` -- `Slice.fromBase64` that converts text slice that has base64 to binary representation (both classic and url) +- `Slice.fromBase64` that converts text slice that has base64 to binary representation (both classic and URL) - `Slice.asCell`, `Builder.asCell`, `Cell.asSlice`, `Builder.asCell` convenience functions -- `Slice.loadCoins` that reads coins from slice -- `myBalance` that returns current balance of a contract before execution phase +- `Slice.loadCoins` that reads coins from a slice +- `myBalance` that returns the current balance of a contract before the execution phase ### Changed -- `contractAddress` now accepts single argument of type `StateInit` and always produces address for workchain. Old method is renamed to `contractAddressExt`. -- `hashCell` and `hashSlice` are now extension function `hash` on `Slice` and `Cell` -- Removed some keywords such as `message`, `contract`, `init` to allow use this names as variable names +- `contractAddress` now accepts a single argument of type `StateInit` and always produces an address for the workchain. The old method is renamed to `contractAddressExt`. +- `hashCell` and `hashSlice` are now extension functions `hash` on `Slice` and `Cell` +- Removed some keywords such as `message`, `contract`, `init` to allow the use of these names as variable names - Renamed `receiveBounced` to `bounced` ### Fixed @@ -352,4 +352,4 @@ Fixing missing NPM release ### Added - `supported_interfaces` TEP support. TACT now automatically builds a list of supported interfaces of a contract -- `IPFS`-based ABI reporting. TACT now automatically calculates and embeds ABI hash into smart contract and prepares a file to upload to IPFS. +- `IPFS`-based ABI reporting. TACT now automatically calculates and embeds ABI hash into smart contracts and prepares a file to upload to IPFS. diff --git a/pages/language/guides/config.mdx b/pages/language/guides/config.mdx index 602dd12b..209eefdc 100644 --- a/pages/language/guides/config.mdx +++ b/pages/language/guides/config.mdx @@ -1,6 +1,6 @@ # Configuration -`tact.config.json` is an entry point to a Tact projects. It is a JSON file that contains the list of all projects and compiler parameters. +`tact.config.json` is an entry point to Tact projects. It is a JSON file that contains the list of all projects and compiler parameters. ## Project description @@ -14,7 +14,7 @@ Each project is described by the following fields: ## Parameters Tact support next parameters: -* `debug: true`. Enables debug output of a contracts. It is useful for debugging purposes. Enabling this contract would report that it was compiled in debug mode using `supported_interfaces` method. +* `debug: true`. Enables debug output of a contract. It is useful for debugging purposes. Enabling this contract would report that it was compiled in debug mode using the `supported_interfaces` method. * `masterchain: true`. Enables [masterchain support](/language/guides/masterchain) in the contract. ## Example @@ -41,4 +41,4 @@ Tact support next parameters: Tact support next experimental parameters: -* `inline: true`. Enables inlining of all functions in contracts. Could reduce gas usage at the cost of bigger contract. +* `inline: true`. Enables inlining of all functions in contracts. Could reduce gas usage at the cost of a bigger contract. diff --git a/pages/language/guides/constants.mdx b/pages/language/guides/constants.mdx index dc6d4113..1834b2bb 100644 --- a/pages/language/guides/constants.mdx +++ b/pages/language/guides/constants.mdx @@ -1,16 +1,16 @@ # Constants -Constants in Tact could be a little bit more advanced than in popular languages: they could be virtual and abstract one. Smart contracts often need to implement multiple traits and sometimes you need to configure some of them in compile time. Constructors in traits are prohibited due their unpredicted behavior. So, we have to use constants and fields instead to pass values to them. it is job of a main contract to implement values and constants for all traits. +Constants in Tact could be a little bit more advanced than in popular languages: they could be virtual and abstract. Smart contracts often need to implement multiple traits and sometimes you need to configure some of them in compile time. Constructors in traits are prohibited due to their unpredicted behavior. So, we have to use constants and fields instead to pass values to them. It is the job of a main contract to implement values and constants for all traits. ## Simple constant -Let's start with a simple constant. It is a value that is defined in compile time and cannot be changed. You can define a constant on top level or inside a constract/trait. Let's define a constant on top level: +Let's start with a simple constant. It is a value that is defined in compile time and cannot be changed. You can define a constant on the top level or inside a contract/trait. Let's define a constant on top level: ```tact const MY_CONSTANT: Int = 42; ``` -Similar for trait and contracts: +Similar for traits and contracts: ```tact trait MyTrait { @@ -24,7 +24,7 @@ contract MyContract { ## Virtual and abstract constants -Virtual constants is the constants that could be defined in trait, but changed in contract. It is useful when you need to configure some of the traits in compile time. Let's define a virtual constant and an abstract one: +Virtual constants are the constants that could be defined in a trait but changed in a contract. It is useful when you need to configure some of the traits in compile time. Let's define a virtual constant and an abstract one: ```tact trait MyTrait { @@ -36,7 +36,7 @@ trait MyAbstractTrait { } ``` -Now you can overwrite defaults in contract: +Now you can overwrite defaults in the contract: ```tact contract MyContract with MyTrait, MyAbstractTrait { diff --git a/pages/language/guides/debug.mdx b/pages/language/guides/debug.mdx index 3d5310c9..0a4f1ff7 100644 --- a/pages/language/guides/debug.mdx +++ b/pages/language/guides/debug.mdx @@ -1,14 +1,14 @@ # Debugging Tact Contracts -Tact has a first-class support for Jest and `@tact-lang/emulator` for contract tests and debugging. Preferred type of tests are the one with inline snapshots. They are easy to write and easy to debug. +Tact has first-class support for Jest and `@tact-lang/emulator` for contract tests and debugging. The preferred type of test is the one with inline snapshots. They are easy to write and easy to debug. -For quick start, it is better to use `tact-template` that has everything built in. +For a quick start, it is better to use `tact-template` that has everything built in. ## Printing out debug data Tact has a built-in `dump` function that is similar to the one in FunC that allows you to print out data in your contract. It is very useful for debugging. -To make `dump` work you need to enable feature `debug` in `tact.conf.json`. +To make `dump` work you need to enable the feature `debug` in `tact.conf.json`. Example: ```tact @@ -19,7 +19,7 @@ dump(a != null); ## Using `@tact-lang/emulator` -Ton Emulator allows you to have a small virtual blockchain in your nodejs code. This library is built specifically for testing smart contracts in unit tests. +Ton Emulator allows you to have a small virtual blockchain in your Node.js code. This library is built specifically for testing smart contracts in unit tests. ```typescript import { ContractSystem } from '@tact-lang/emulator'; @@ -52,11 +52,11 @@ let logger = system.log(contract.address); // Sending a message // -// First we enqueue a messages. NOTE: You can enqueue multiple messages in row +// First we enqueue messages. NOTE: You can enqueue multiple messages in a row await contract.send(treasure, { value: toNano(1) }, { $$type: "Deploy", queryId: 0n }); await contract.send(treasure, { value: toNano(1) }, { $$type: "Increment" }); -// Run system until there are no more messages +// Run the system until there are no more messages await system.run(); // @@ -108,7 +108,7 @@ describe("contract", () => { ### Generating snapshots -After running `yarn jest` command, the line with `toMatchInlineSnapshot` of the test will be automatically updated with a snapshot of the output. +After running the `yarn jest` command, the line with `toMatchInlineSnapshot` of the test will be automatically updated with a snapshot of the output. ```typescript // ... @@ -163,4 +163,4 @@ After running `yarn jest` command, the line with `toMatchInlineSnapshot` of the ### Updating snapshots -When you change your contract, your snapshots will be outdated. For example, gas usage or addresses was changed. To update them, you need to run `yarn jest -u` command. +When you change your contract, your snapshots will be outdated. For example, gas usage or addresses were changed. To update them, you need to run the `yarn jest -u` command. diff --git a/pages/language/guides/deploy.mdx b/pages/language/guides/deploy.mdx index 7a79fb4d..3d8982ac 100644 --- a/pages/language/guides/deploy.mdx +++ b/pages/language/guides/deploy.mdx @@ -1,10 +1,10 @@ # Deploy -Tact Deployer is a small library that integrates with [TON Verifier](https://verifier.ton.org) that allows you to deploy your contracts safely using your favorite wallet without needing to manage keys or deploy contracts manually. Tact Deployer also automatically verifies your contract's source code and you can be sure that you compiler is not compromised. +Tact Deployer is a small library that integrates with [TON Verifier](https://verifier.ton.org) that allows you to deploy your contracts safely using your favorite wallet without needing to manage keys or deploy contracts manually. Tact Deployer also automatically verifies your contract's source code and you can be sure that your compiler is not compromised. ## Requirements -Your contract MUST have `Deployer` trait from `@stdlib/deploy` package to be able to use Tact Deployer. +Your contract MUST have the `Deployer` trait from the `@stdlib/deploy` package to be able to use Tact Deployer. ## Installation @@ -16,7 +16,7 @@ yarn add @tact-lang/deployer ## How to use -When you build your smart contracts using Tact, it produces a package (*.pkg) file that has all required information about built smart contract. To deploy your smart contract, you need to create a deployer instance and pass your package file to it and provide initial data for your contract. +When you build your smart contracts using Tact, it produces a package (*.pkg) file that has all the required information about the built smart contract. To deploy your smart contract, you need to create a deployer instance, pass your package file to it and provide initial data for your contract. ```typescript import * as fs from 'fs'; @@ -33,7 +33,7 @@ let owner = Address.parse(''); // Our sample contract has a let init = await SampleTactContract.init(owner); // Create initial data for our contract // Calculations -let address = contractAddress(0, init); // Calculate contract address. MUST match with address in the verifier +let address = contractAddress(0, init); // Calculate contract address. MUST match with the address in the verifier let data = init.data.toBoc(); // Create init data let pkg = fs.readFileSync( // Read package file path.resolve(outputPath, packageName) @@ -47,4 +47,4 @@ console.log('Address: ' + address.toString({ testOnly: testnet })); console.log('Deploy link: ' + link); ``` -After following this link you will be able to deploy and verify you smart contract. \ No newline at end of file +After following this link you will be able to deploy and verify your smart contract. \ No newline at end of file diff --git a/pages/language/guides/external.mdx b/pages/language/guides/external.mdx index 2b994554..4b548309 100644 --- a/pages/language/guides/external.mdx +++ b/pages/language/guides/external.mdx @@ -3,7 +3,7 @@ import { Callout } from "nextra-theme-docs"; # External Messages - External messages support must be enabled explicitly in project configuration. + External message support must be enabled explicitly in the project configuration. Without enabling it compilation would fail. @@ -28,9 +28,9 @@ External messages are not accepted automatically. You need to accept them manual 10k gas is a very small limit, and Tact itself can consume a sizable amount of gas before it even reaches your code. You should always test the gas usage of your contracts and verify that everything is working as intended. - The 10k gas limit for External message is based on the parameter we set by the + The 10k gas limit for external messages is based on the parameter we set by the validator for the whole blockchain of the `gas_limit` field. You can take - reference here: + the reference here: - https://docs.ton.org/develop/smart-contracts/guidelines/accept#external-messages - https://docs.ton.org/develop/howto/blockchain-configs#param-20-and-21 @@ -58,7 +58,7 @@ To enable external messages support, please enable it in the project configurati ## External receivers -External receivers are defined the same way as internal one, but using `external` keyword instead of `receive`: +External receivers are defined the same way as internal ones, but using the `external` keyword instead of `receive`: ```tact contract SampleContract { diff --git a/pages/language/guides/func.mdx b/pages/language/guides/func.mdx index ecbae053..3b41d620 100644 --- a/pages/language/guides/func.mdx +++ b/pages/language/guides/func.mdx @@ -1,18 +1,18 @@ # Compatibility with func -Tact itself compiles to `func` and allows to map Tact entities directly to various `func` and `tl-b` types. +Tact itself compiles to `func` and maps Tact entities directly to various `func` and `tl-b` types. ## Convert types -Primitive types in `tact` are directly mapped to `func` one. All rules about copying variables are the same. One of the big differences is that there are no visible mutation operator in `tact` and most `Slice` operations mutate variables in place. +Primitive types in `tact` are directly mapped to `func` one. All rules about copying variables are the same. One of the big differences is that there are no visible mutation operators in `tact` and most `Slice` operations mutate variables in place. ## Convert serialization -Tact structs and messages serialization is automatic unlike `func` where you need to define serialization logic manually. To build a `tact` types that serializes to specific `tl-b`. +Tact structs and messages serialization is automatic unlike `func` where you need to define serialization logic manually. To build a `tact` type that serializes to specific `tl-b`. -Tact auto-layout algorithm is greedy. Means that it takes next variable, calculates it's size and tries to fit into a current cell. If it doesn't fit, it creates a new cell and continues. All inner structs for auto-layout are flattened before allocation. +The tact auto-layout algorithm is greedy. This means that it takes the next variable, calculates its size, and tries to fit it into a current cell. If it doesn't fit, it creates a new cell and continues. All inner structs for auto-layout are flattened before allocation. -All, except `Address`, optional types are serialized as `Maybe` in `tl-b`. There are no support for `Either` since it does not define what to pick during serialization in some cases. +All, except `Address`, optional types are serialized as `Maybe` in `tl-b`. There is no support for `Either` since it does not define what to pick during serialization in some cases. ### Examples @@ -96,7 +96,7 @@ struct SomeValue { ## Convert received messages to `op` operations -Tact generates a unique `op` for every received typed message, but it can be overwritten. +Tact generates a unique `op` for every received typed message, but it can be overwritten. Code in `func`: ```func @@ -165,9 +165,9 @@ get fun seqno(): Int { ### Tensor return types -In `func` there are a difference between tensor type `(int, int)` and `(int, (int))`, but for TVM there are no difference, they all represent a stack of two ints. +In `func` there is a difference between tensor type `(int, int)` and `(int, (int))`, but for TVM there are no differences, they all represent a stack of two ints. -To convert tensor that returned from `func` get-method, you need to define a `struct` that has same amount of fields as tensor and in the same order. +To convert the tensor that returned from the `func` get-method, you need to define a `struct` that has the same amount of fields as the tensor and in the same order. Code in `func`: ```func @@ -194,7 +194,7 @@ get fun get_wallet_data(): JettonWalletData { ### Tuple return type -In `func` if you are returning a tuple, instead of a tensor you need to follow process as for tensor type, but define return type of a get method as optional. +In `func` if you are returning a tuple, instead of a tensor you need to follow the process for tensor type, but define return type of a get method as optional. Code in `func`: ```func @@ -248,7 +248,7 @@ get fun get_contract_state(): ContractState { ### Arguments mapping -Conversion of get-methods arguments are straight forward. Each argument is mapped as-is to `func` one, and each tuple is mapped to a struct. +Conversion of get-methods arguments is forward. Each argument is mapped as-is to `func` one, and each tuple is mapped to a struct. Code in `func`: ```func diff --git a/pages/language/guides/functions.mdx b/pages/language/guides/functions.mdx index 8142389c..f401260a 100644 --- a/pages/language/guides/functions.mdx +++ b/pages/language/guides/functions.mdx @@ -11,7 +11,7 @@ Functions in Tact could be defined in different ways: ## Global static functions -You can define global function anywhere in you program: +You can define global function anywhere in your program: ```tact fun pow(a: Int, c: Int): Int { @@ -25,10 +25,10 @@ fun pow(a: Int, c: Int): Int { ## Extension function -Extension functions allows you to implement extension for any possible type. +Extension functions allow you to implement extensions for any possible type. > **Warning** -> Name of the first argument MUST be named `self` and type of this argument is the type you are extending. +> The name of the first argument MUST be named `self` and the type of this argument is the type you are extending. ```tact extends fun pow(self: Int, c: Int) { @@ -42,7 +42,7 @@ extends fun pow(self: Int, c: Int) { ## Mutable functions -Mutable functions are performing mutation of a value replacing it with an execution result. To perform mutation function must change `self` value. +Mutable functions are performing mutation of a value replacing it with an execution result. To perform mutation, the function must change the `self` value. ```tact extends mutates fun pow(self: Int, c: Int) { @@ -56,10 +56,10 @@ extends mutates fun pow(self: Int, c: Int) { ## Native functions -Native functions are direct binding to a func functions: +Native functions are direct bindings of func functions: > **Note** -> Native functions could be also mutable and extension one +> Native functions could be also mutable and extension ones. ```tact @name(store_uint) @@ -71,14 +71,14 @@ extends mutates native loadInt(self: Slice, l: Int): Int; ## Receiver functions -Receiver functions are special function that are responsible of receiving messages in contracts and could be defined only within a contract or trait. +Receiver functions are special functions that are responsible for receiving messages in contracts and could be defined only within a contract or trait. ```tact contract Treasure { // ... - // This means that this contract can receive comment "Increment" and this function would be called for such messages + // This means that this contract can receive the comment "Increment" and this function would be called for such messages receive("Increment") { self.counter = self.counter + 1; } @@ -87,7 +87,7 @@ contract Treasure { ## Getter Functions -Getter functions that defines getters on smart contract and can be defined only within a contract or trait. +Getter functions define getters on smart contracts and can be defined only within a contract or trait. ```tact contract Treasure { diff --git a/pages/language/guides/lifecycle.mdx b/pages/language/guides/lifecycle.mdx index 04a77792..3117bfdf 100644 --- a/pages/language/guides/lifecycle.mdx +++ b/pages/language/guides/lifecycle.mdx @@ -1,26 +1,26 @@ # Message Lifecycle -There are several stages of a message processing by a contract, there are more of them, but we would focus on most important ones: +There are several stages of message processing by a contract, there are more of them, but we would focus on the most important ones: ## Receive Phase This phase combines multiple low-level phases. -It starts by adding a **message value to the contract balance**. Value of incoming message is a maximum price that a contract can pay for a gas to process this message. Contract is able to overwrite this limit, but it is not recommended and suitable only for advanced developers since it could lead to a contract being drained. 1 million of gas is a maximum amount that contract can spend in a single contract that equals to 1 TON (currently). If message value is zero than execution is aborted. +It starts by adding a **message value to the contract balance**. The value of an incoming message is the maximum price that a contract can pay for gas to process this message. The contract can overwrite this limit, but it is not recommended and is suitable only for advanced developers since it could lead to a contract being drained. 1 million of gas is the maximum amount that a contract can spend in a single contract which equals 1 TON (currently). If the message value is zero then execution is aborted. -Then some (usually small amount) of nanotons is substracted from contract balance for storage. This means that you can't perfectly predict balance changes and have to adjust your code to this instability. +Then some (usually a small amount) of nanotons is subtracted from the contract balance for storage. This means that you can't perfectly predict balance changes and have to adjust your code to this instability. -Then it deploys a contract if it is not deployed yet and message contains init package. If init package isn't present, it would be ignored. +Then it deploys a contract if it is not deployed yet and the message contains the init package. If the init package isn't present, it will be ignored. ## Compute Phase -This phase executes code of a smart contract and produces a list of actions or an exception. Currently only two types of actions are supported: **send message** and **reserve**. +This phase executes the code of a smart contract and produces a list of actions or an exception. Currently, only two types of actions are supported: **send message** and **reserve**. -Sending a message could use a fixed value or a some dynamic value like **remaining value of a message** - the remainings of value of incoming message. Sending a message could be with a flag `SendIgnoreErrors` that would ignore errors during message sending and would continue to the next action. This flag useful if you have multiple actions. When sending a message with a some value, it first substracts this value from the incoming value and only then from contract balance (before processing). +Sending a message could use a fixed value or a dynamic value like **remaining value of a message** - the remaining of value of the incoming message. Sending a message could be with a flag `SendIgnoreErrors` that would ignore errors during message sending and would continue to the next action. This flag is useful if you have multiple actions. When sending a message with some value, it first subtracts this value from the incoming value and only then from the contract balance (before processing). ## Action Phase Actions are executed in sequence, but bear in mind: **EXCEPTION DURING PROCESSING ACTIONS WOULDN'T REVERT THE TRANSACTION** -For example, if you substracted 1 ton from customer's balance and then would send invalid message, that could lead to a situation when customer's balance is substracted, but he wouldn't receive it. +For example, if you subtract 1 ton from a customer's balance and then send an invalid message, that could lead to a situation when the customer's balance is subtracted, but he wouldn't receive it. diff --git a/pages/language/guides/masterchain.mdx b/pages/language/guides/masterchain.mdx index ea88e0e0..18548072 100644 --- a/pages/language/guides/masterchain.mdx +++ b/pages/language/guides/masterchain.mdx @@ -3,19 +3,19 @@ import { Callout } from 'nextra-theme-docs' # Masterchain -Masterchain support must be enabled explicitly in project configuration. Without enabling it all masterchain addresses will be treated as invalid. +Masterchain support must be enabled explicitly in the project configuration. Without enabling it all masterchain addresses will be treated as invalid. Most of the contract developers don't need a masterchain. Masterchain is needed only for participating in elections or storing libraries. If you don't need to participate in elections or store libraries, you don't need a masterchain. ## How contract is protected from masterchain -Most of the contracts written in `func` enforce all incoming addresses to be `basechain` one. This is done to prevent masterchain addresses from being used in the contract. Tact does this **by default**. +Most of the contracts written in `func` enforce all incoming addresses to be `basechain` ones. This is done to prevent masterchain addresses from being used in the contract. Tact does this **by default**. -What prohibited to do without masterchain support enabled: -* Deploy contract to masterchain. `init` function would throw `Masterchain support is not enabled for this contract` error for every message. +What is prohibited to do without masterchain support enabled: +* Deploy contract to masterchain. The `init` function would throw a `Masterchain support is not enabled for this contract` error for every message. * Receive messages from masterchain accounts. -* Receive structs that has masterchain addresses in it. +* Receive structs that have masterchain addresses in them. * Send messages to masterchain accounts. * Use masterchain addresses in arguments of get methods. diff --git a/pages/language/guides/programmatic.mdx b/pages/language/guides/programmatic.mdx index 246ca119..8b1e7cd5 100644 --- a/pages/language/guides/programmatic.mdx +++ b/pages/language/guides/programmatic.mdx @@ -2,10 +2,10 @@ import { Callout } from "nextra-theme-docs"; # Programmatic API -You can invoke Tact compiler from your own code in node and browser environments. +You can invoke the Tact compiler from your code in node and browser environments. - This API is not released yet. It will be released in the 1.0.0 version. + This API has not been released yet. It will be released in the 1.0.0 version. ## Run compiler in browser @@ -36,7 +36,7 @@ let successful = await run({ config, fs }); ## Contract verification -You can always verify compiled package with the `verify` function. +You can always verify the compiled package with the `verify` function. ```ts import { verify } from "@tact-lang/compiler"; diff --git a/pages/language/guides/receive.mdx b/pages/language/guides/receive.mdx index 96543ede..8bf802d2 100644 --- a/pages/language/guides/receive.mdx +++ b/pages/language/guides/receive.mdx @@ -1,16 +1,16 @@ # Receive messages -TON is a distributed blockchain that means that communication between contracts is done by sending and receiving messages. The most common type of a message is internal message - message sent from one contract (or a wallet) to another. +TON is a distributed blockchain which means that communication between contracts is done by sending and receiving messages. The most common type of message is the internal message - a message sent from one contract (or a wallet) to another. ## Receive internal messages -To receive a message of required type, you need to declare a receiver function, for example `receive("increment")`. This notation means declaration of a `receiver` function that will be called when a text with value `"increment"` is sent to the contract. The function body can modify the state of the contract and send messages to other contracts. It is impossible to call `receiver` directly. If you need to reuse some logic you can declare a function and call it from `receiver`. +To receive a message of the required type, you need to declare a receiver function, for example, `receive("increment")`. This notation means the declaration of a `receiver` function that will be called when a text with the value `"increment"` is sent to the contract. The function body can modify the state of the contract and send messages to other contracts. It is impossible to call `receiver` directly. If you need to reuse some logic you can declare a function and call it from `receiver`. There are several receiver functions. All receiver functions are processed in the order they are listed below: * `receive()` - called when an empty message is sent to the contract * `receive("message")` - called when a text message with a specific comment is sent to the contract * `receive(str: String)` - called when an arbitrary text message is sent to the contract -* `receive(msg: MyMessage)` - called when binary message of type `MyMessage` is sent to the contract +* `receive(msg: MyMessage)` - called when a binary message of type `MyMessage` is sent to the contract * `receive(msg: Slice)` - called when binary message of unknown type is sent to the contract diff --git a/pages/language/guides/send.mdx b/pages/language/guides/send.mdx index fe97dd2e..cb9d2144 100644 --- a/pages/language/guides/send.mdx +++ b/pages/language/guides/send.mdx @@ -2,16 +2,16 @@ TON blockchain is a message-based one to communicate with other contracts you need to send messages. -Message consists of: -* `value` in TON - amount of TON you want to send with the message. This value is used to cover gas fees on receiver side. -* `bounce` - if set to `true` (default) then message will be bounced back to sender if receiver contract doesn't exist or wasn't able to process the message. +The message consists of: +* `value` in TON - the amount of TON you want to send with the message. This value is used to cover gas fees on the receiver side. +* `bounce` - if set to `true` (default) then the message will be bounced back to the sender if the receiver contract doesn't exist or wasn't able to process the message. * `code` and `data` - init package, useful for deployments * `body` - message body as `Cell` -* `mode` - 8-bit flag that configures how to send message +* `mode` - an 8-bit flag that configures how to send a message ## Send simple reply -Simplest message is a reply to the incoming message with returning all excess value of a message: +The simplest message is a reply to the incoming message returning all excess value of a message: ```tact self.reply("Hello, World!".asComment()); // asComment converts string to a Cell with a comment @@ -19,11 +19,11 @@ self.reply("Hello, World!".asComment()); // asComment converts string to a Cell ## Send message -If you need a more advanced logic you can use `send` function directly. +If you need more advanced logic you can use the `send` function directly. -This example sends a message to the `to` address with `value` of 1 TON and `body` of a comment with a string "Hello, World!". +This example sends a message to the `to` address with a `value` of 1 TON and the `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. **No error during sending phase would revert a transaction.** +`SendIgnoreErrors` means that even when an error occurs during message sending next messages would be sent anyway. **No error during the sending phase would revert a transaction.** ```tact let to: Address = ...; @@ -39,7 +39,7 @@ send(SendParameters{ ## Send typed message -To send a binary typed message you can use next code: +To send a binary typed message you can use the following code: ```tact let to: Address = ...; @@ -55,7 +55,7 @@ send(SendParameters{ ## Deploy contract -To deploy contract you need to calculate it's address and init package, then send it with an initial message. You can always send init package with a message and it would be ignored, but would cost more than the message without init package. +To deploy a contract you need to calculate its address and init package, then send it with an initial message. You can always send an init package with a message and it would be ignored, but would cost more than the message without an init package. ```tact let init: StateInit = initOf SecondContract(arg1, arg2); diff --git a/pages/language/guides/statements.mdx b/pages/language/guides/statements.mdx index 04e10aaa..dd0e7e4d 100644 --- a/pages/language/guides/statements.mdx +++ b/pages/language/guides/statements.mdx @@ -2,7 +2,7 @@ ## Variable declaration -Declaring variable always requires initial value and an explicit type: +Declaring variable always requires an initial value and an explicit type: ```tact let value: Int = 123; @@ -10,7 +10,7 @@ let value: Int = 123; ## Static function call -Anywhere in the function body a static functions can be called: +Anywhere in the function body, a static function can be called: ```tact let expiration: Int = now() + 1000; // now() is stdlib static function @@ -28,12 +28,12 @@ let some: String = 95.toString(); // toString() is a stdlib function that is def Tact supports operations: -- `!!` suffix operator - enforce non-null value, defined only for nullable types. -- `!` - logical inversion, defined only for `Bool` type. -- `/`, `*`, `%` - division and multiplication operations, defined only for `Int` type +- `!!` suffix operator - enforces non-null value, defined only for nullable types. +- `!` - logical inversion, defined only for the `Bool` type. +- `/`, `*`, `%` - division and multiplication operations, defined only for the `Int` type - `-`, `+` - arithmetic operations, defined only for `Int` type - `!=`, `==` - equality operations -- `>`, `<`, `>=`, `<=` - compare operations, defined only for `Int` type +- `>`, `<`, `>=`, `<=` - compare operations, defined only for the `Int` type - `&&`, `||` - logical `AND` and `OR` ## Loops @@ -50,7 +50,7 @@ repeat(10) { ``` > **Note** -> Repeat number must be 32 bit int or out of range exception is thrown. Negative values are ignored. +> Repeat number must be a 32-bit int or of range exception is thrown. Negative values are ignored. ### While loop diff --git a/pages/language/guides/types.mdx b/pages/language/guides/types.mdx index 14bd87cf..ab4f5a21 100644 --- a/pages/language/guides/types.mdx +++ b/pages/language/guides/types.mdx @@ -7,23 +7,23 @@ Every variable, item, and value in a Tact program has a type: * Structs and Messages * Contracts and Traits -Also most primitive types, structs and messages could be nullable. +Also, most primitive types, structs, and messages could be nullable. ## Primitive types -* Int - all integers in Tact are 257 bit signed integers. +* Int - all integers in Tact are 257-bit signed integers. * Bool - classical boolean with true/false values. * Address - standard address. -* Slice, Cell, Builder - low level primitive of TON VM. +* Slice, Cell, Builder - low-level primitive of TON VM. * String - type that represents text strings in TON VM. -* StringBuilder - helper type that allows you to concatenate strings in gas-efficient way +* StringBuilder - helper type that allows you to concatenate strings in a gas-efficient way ## Structs and Messages -Structs and Messages are almost the same thing with an only difference that message has a header in it's serialization and therefore could be used as receivers. +Structs and Messages are almost the same thing with the only difference being that a message has a header in its serialization and therefore could be used as receivers. > **Warning** -> Currently circular **types** are not possible. Meaning that struct/message **A** can't have field of a struct/message **B** that have field of a struct/message **A**. +> Currently circular **types** are not possible. This means that struct/message **A** can't have a field of a struct/message **B** that has a field of the struct/message **A**. Example: ```tact @@ -40,7 +40,7 @@ message SetValue { ## Maps -The type `map` is used as way to associate data with corresponding keys. +The type `map` is used as a way to associate data with corresponding keys. Possible key types: * Int @@ -61,7 +61,7 @@ contract HelloWorld { ## Contracts -Contracts are the main entry of a smart contract on TON blockchain. It holds all functions, getters and receivers of a contract. +Contracts are the main entry of a smart contract on the TON blockchain. It holds all functions, getters, and receivers of a contract. ```tact contract HelloWorld { @@ -83,7 +83,7 @@ contract HelloWorld { ## Traits -Tact doesn't support classical class inheritance, but instead introduces concept of **traits**. Trait defines functions, receivers and required fields. Trait is like abstract classes, but it does not define how and where fields must be stored. **All** fields from all traits must be explicitly declared in the contract itself. Traits itself also don't have constructors and all initial field initialization also must be done in main contract. +Tact doesn't support classical class inheritance, but instead introduces the concept of **traits**. Trait defines functions, receivers, and required fields. The trait is like abstract classes, but it does not define how and where fields must be stored. **All** fields from all traits must be explicitly declared in the contract itself. Traits itself also don't have constructors and all initial field initialization also must be done in the main contract. ```tact trait Ownable { @@ -99,7 +99,7 @@ trait Ownable { } ``` -And contract that uses trait: +And the contract that uses trait: ```tact contract Treasure with Ownable { diff --git a/pages/language/guides/upgrades.mdx b/pages/language/guides/upgrades.mdx index d3fd9a2e..5f10d9c0 100644 --- a/pages/language/guides/upgrades.mdx +++ b/pages/language/guides/upgrades.mdx @@ -1,3 +1,3 @@ # Contracts upgrades -Tact currently doesn't allow contract upgrades since Tact contracts have more convoluted nature than the ones in `func`. It is theoretically possible, but required tools are not here. \ No newline at end of file +Tact currently doesn't allow contract upgrades since Tact contracts have a more convoluted nature than the ones in `func`. It is theoretically possible, but the required tools are not here. \ No newline at end of file