From 2ad6e85f3bf1649e74669a74b45eaca632376b7d Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 05:11:51 +0100 Subject: [PATCH 1/6] feat(docs): compilation report --- CHANGELOG.md | 1 + docs/astro.config.mjs | 5 +- docs/src/content/docs/book/compile.mdx | 104 ++++++++++++++++++++++ docs/src/content/docs/book/debug.mdx | 4 +- docs/src/content/docs/book/deploy.mdx | 3 - docs/src/content/docs/ref/core-common.mdx | 2 +- src/generator/writeReport.ts | 38 ++++---- 7 files changed, 132 insertions(+), 25 deletions(-) create mode 100644 docs/src/content/docs/book/compile.mdx diff --git a/CHANGELOG.md b/CHANGELOG.md index eaf53e5e6..2b14db9ef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -71,6 +71,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Fixed links in Chinese translation: PR [#1206](https://github.com/tact-lang/tact/pull/1206) - Added a note on 255 being the maximum number of messages that can be sent during action phase: PR [#1237](https://github.com/tact-lang/tact/pull/1237) - Added onchain metadata creation for NFTs and Jettons to the cookbook: PR [#1236](https://github.com/tact-lang/tact/pull/1236) +- Added a compilation-related page with the description of the compilation report: PR [#1309](https://github.com/tact-lang/tact/pull/1309) ### Release contributors diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index fbc654998..8c8ff3779 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -180,10 +180,11 @@ export default defineConfig({ label: 'Going places', translations: { 'zh-CN': '前往各地' }, attrs: { class: 'sidebar-separator' }, - link: 'book/deploy#', + link: 'book/compile#', }, - { slug: 'book/deploy' }, + { slug: 'book/compile' }, { slug: 'book/debug' }, + { slug: 'book/deploy' }, { slug: 'book/upgrades' }, { slug: 'book/import' }, { slug: 'book/config' }, diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx new file mode 100644 index 000000000..90d0ad133 --- /dev/null +++ b/docs/src/content/docs/book/compile.mdx @@ -0,0 +1,104 @@ +--- +title: Compilation +description: "How to compile Tact smart contracts, as well as details on the build artifacts that are provided." +prev: + link: /book/message-mode + label: Message mode +--- + +import { Badge } from '@astrojs/starlight/components'; + +:::note + + This page is still being written as per [#1136](https://github.com/tact-lang/tact-docs/issues/1136). + +::: + +The Tact compiler can produce various outputs, ranging from the [BoC](/book/cells#cells-boc) of the compiled contract to various supplementary files, such as the [compilation report](#report) or the [contract package](/ref/evolution/otp-006), which is the JSON file with the `.pkg` extension that one can use to [verify the smart contract's origin](https://verifier.ton.org). + +With the proper [configuration settings](/book/config), you can customize the behavior of the compiler to skip the generation of some or all the [build artifacts](#artifacts), and even control the addition or exclusion of [getters for supported interfaces](/book/contracts#interfaces). + +Since the Tact compiler is a command-line program, some of the configuration settings can be set directly. When inside a folder with a Tact-based project, such as one created using the [Blueprint](https://github.com/ton-org/blueprint) or from the [tact-template](https://github.com/tact-lang/tact-template), refer to the `npx tact --help{:shell}` command for further instructions. + +## Build artifacts {#artifacts} + +A number of build artifacts can be produced per compilation of each contract. Some of the artifacts can be omitted using [configuration settings](/book/config). + +The location of the artifacts depends on the [`output`](/book/config#projects-output) field of the [`tact.config.json`](/book/config). In [Blueprint][bp]-based projects, `output` is not used and all generated files are always placed in `build/ProjectName/`. + +### Compilation report, `.md` {#report} + +Every markdown compilation report first features the name of the contract that it was prepared for and then the byte size of the contract compiled to [BoC](/book/cells#cells-boc). + +The following sub-headings describe the respective sections of the `.md` report. + +#### Structures {#structures} + +

+ +The first section introduces the present structures, i.e. some of the [composite types](/book/types#composite-types), [Structs and Messages](/book/structs-and-messages) that are declared or imported directly in the contract code, as well as those exposed from the Core standard library. + +Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and Tact signatures. + +For example: + +```md +Total structures: 10 + +### StateInit +TL-B: `_ code:^cell data:^cell = StateInit` +Signature: `StateInit{code:^cell,data:^cell}` + +### StdAddress +TL-B: `_ workchain:int8 address:uint256 = StdAddress` +Signature: `StdAddress{workchain:int8,address:uint256}` + +...etc. +``` + +#### Get methods {#getters} + +This section specifies the number of available get methods or [getter functions](/book/functions#getter-functions) and outlines them with their argument names, if any. + +For example: + +```md +Total get methods: 2 + +## lshift +Argument: x + +## gas +``` + +There, the `lshift(){:tact}` getter has a single argument `x`, whereas the `gas(){:tact}` getter has no arguments. + +#### Exit codes {#exit-codes} + +This section lists all default [exit codes](/book/exit-codes), as well as those generated from the error messages of the [`require(){:tact}`](/ref/core-debug#require), along with those messages for your convenience. + +For example: + +```md +* 2: Stack underflow +* 3: Stack overflow +...etc. +* 135: Code of a contract was not found +* 42933: Hey, I'm the error message of require() +``` + +There, the [exit codes](/book/exit-codes) in the range from $0$ to $255$ are those reserved by TON Blockchain or Tact compiler, while the exit code of $42933$ is produced by the respective call to the [`require(){:tact}`](/ref/core-debug#require) function. + +#### Trait inheritance diagram {#trait-diagram} + +This section shows a [Mermaid][mm] diagram of inherited [traits](/book/types#traits), including the [`BaseTrait{:tact}`](/ref/core-base). + +#### Contract inheritance diagram {#contract-diagram} + +This section shows a [Mermaid][mm] diagram of [contract](/book/contracts) dependencies, i.e. the [traits](/book/types#traits) that it depends upon. + +[struct]: /book/structs-and-messages#structs +[message]: /book/structs-and-messages#messages + +[tlb]: https://docs.ton.org/develop/data-formats/tl-b-language +[mm]: https://mermaid.js.org/ diff --git a/docs/src/content/docs/book/debug.mdx b/docs/src/content/docs/book/debug.mdx index 45ad2595c..77b28d521 100644 --- a/docs/src/content/docs/book/debug.mdx +++ b/docs/src/content/docs/book/debug.mdx @@ -1,6 +1,6 @@ --- -title: Debugging Tact contracts -description: "Various ways to reveal problems or bugs in Tact code" +title: Debugging and testing +description: "Various ways to reveal and prevent problems or bugs in Tact code" --- import { LinkCard, CardGrid, Steps, Tabs, TabItem } from '@astrojs/starlight/components'; diff --git a/docs/src/content/docs/book/deploy.mdx b/docs/src/content/docs/book/deploy.mdx index 92b5ba397..23c0573e6 100644 --- a/docs/src/content/docs/book/deploy.mdx +++ b/docs/src/content/docs/book/deploy.mdx @@ -1,9 +1,6 @@ --- title: Deployment description: "Common ways to deploy Tact contracts to testnet or mainnet of TON Blockchain" -prev: - link: /book/message-mode - label: Message mode --- 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. diff --git a/docs/src/content/docs/ref/core-common.mdx b/docs/src/content/docs/ref/core-common.mdx index 5444ece78..e93ee2955 100644 --- a/docs/src/content/docs/ref/core-common.mdx +++ b/docs/src/content/docs/ref/core-common.mdx @@ -98,7 +98,7 @@ Field | Type | Description `bounced` | [`Bool{:tact}`][bool] | [Bounced](https://ton.org/docs/learn/overviews/addresses#bounceable-vs-non-bounceable-addresses) flag of the incoming message. `sender` | [`Address{:tact}`][p] | Internal address of the sender on the TON blockchain. `value` | [`Int{:tact}`][int] | Amount of [nanoToncoins](/book/integers#nanotoncoin) in a message. -`raw` | [`Slice{:tact}`][slice] | The remainder of the message as a [`Slice{:tact}`][slice]. It follows [internal message layout](https://docs.ton.org/develop/smart-contracts/messages#message-layout) of TON starting from the destination [`Address{:tact}`][p] (`dest:MsgAddressInt ` in [TL-B notation](https://docs.ton.org/develop/data-formats/tl-b-language)). +`raw` | [`Slice{:tact}`][slice] | The remainder of the message as a [`Slice{:tact}`][slice]. It follows [internal message layout](https://docs.ton.org/develop/smart-contracts/messages#message-layout) of TON starting from the destination [`Address{:tact}`][p] (`MsgAddressInt` in [TL-B notation](https://docs.ton.org/develop/data-formats/tl-b-language)). Usage example: diff --git a/src/generator/writeReport.ts b/src/generator/writeReport.ts index 62250f53d..c3ce4c959 100644 --- a/src/generator/writeReport.ts +++ b/src/generator/writeReport.ts @@ -9,41 +9,45 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) { const w = new Writer(); const abi = JSON.parse(pkg.abi) as ContractABI; w.write(` - # TACT Compilation Report + # Tact compilation report Contract: ${pkg.name} - BOC Size: ${Buffer.from(pkg.code, "base64").length} bytes + BoC Size: ${Buffer.from(pkg.code, "base64").length} bytes `); w.append(); - // Types - w.write(`# Types`); - w.write("Total Types: " + abi.types!.length); + // Structures + w.write(`## Structures (Structs and Messages)`); + w.write("Total structures: " + abi.types!.length); w.append(); for (const t of abi.types!) { const tt = getType( ctx, t.name.endsWith("$Data") ? t.name.slice(0, -5) : t.name, ); - w.write(`## ${t.name}`); - w.write(`TLB: \`${tt.tlb!}\``); + w.write(`### ${t.name}`); + w.write(`TL-B: \`${tt.tlb!}\``); w.write(`Signature: \`${tt.signature!}\``); w.append(); } // Get methods - w.write(`# Get Methods`); - w.write("Total Get Methods: " + abi.getters!.length); + w.write(`## Get methods`); + w.write("Total get methods: " + abi.getters!.length); w.append(); for (const t of abi.getters!) { w.write(`## ${t.name}`); - for (const arg of t.arguments!) { - w.write(`Argument: ${arg.name}`); + if (t.arguments!.length === 0) { + w.write(`This getter has no arguments`); + } else { + for (const arg of t.arguments!) { + w.write(`Argument: ${arg.name}`); + } } w.append(); } - // Error Codes - w.write(`# Error Codes`); + // Exit codes + w.write(`## Exit codes`); Object.entries(abi.errors!).forEach(([t, abiError]) => { w.write(`* ${t}: ${abiError.message}`); }); @@ -52,8 +56,8 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) { const t = getType(ctx, pkg.name); const writtenEdges: Set = new Set(); - // Trait Inheritance Diagram - w.write(`# Trait Inheritance Diagram`); + // Trait inheritance diagram + w.write(`## Trait inheritance diagram`); w.append(); w.write("```mermaid"); w.write("graph TD"); @@ -75,8 +79,8 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) { writtenEdges.clear(); - // Contract Dependency Diagram - w.write(`# Contract Dependency Diagram`); + // Contract dependency diagram + w.write(`## Contract dependency diagram`); w.append(); w.write("```mermaid"); w.write("graph TD"); From 33a2ea7a2046fdbbef62d3cb609067c6b5b4741f Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 06:02:30 +0100 Subject: [PATCH 2/6] fix: suggestions from the code review --- docs/src/content/docs/book/compile.mdx | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx index 90d0ad133..fc8a290b0 100644 --- a/docs/src/content/docs/book/compile.mdx +++ b/docs/src/content/docs/book/compile.mdx @@ -10,7 +10,7 @@ import { Badge } from '@astrojs/starlight/components'; :::note - This page is still being written as per [#1136](https://github.com/tact-lang/tact-docs/issues/1136). + This page is still being written as per [#1136](https://github.com/tact-lang/tact/issues/1136). ::: @@ -56,6 +56,18 @@ Signature: `StdAddress{workchain:int8,address:uint256}` ...etc. ``` +[TL-B schema][tlb] of each [Message][message] contains its opcode, which is handy for looking up the auto-generated opcodes as well as confirming the [manually provided ones](/book/structs-and-messages#message-opcodes). For example: + +```md +## Deploy +TL-B: `deploy#946a98b6 queryId:uint64 = Deploy` +Signature: `Deploy{queryId:uint64}` + +## Seven +TL-B: `seven#00000007 = Seven` +Signature: `Seven{}` +``` + #### Get methods {#getters} This section specifies the number of available get methods or [getter functions](/book/functions#getter-functions) and outlines them with their argument names, if any. From 364e77985fa85b09fe8c80b7b06e1529a9ef6c10 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 06:15:43 +0100 Subject: [PATCH 3/6] whoopsie --- docs/src/content/docs/book/compile.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx index fc8a290b0..9e5725d8c 100644 --- a/docs/src/content/docs/book/compile.mdx +++ b/docs/src/content/docs/book/compile.mdx @@ -59,11 +59,11 @@ Signature: `StdAddress{workchain:int8,address:uint256}` [TL-B schema][tlb] of each [Message][message] contains its opcode, which is handy for looking up the auto-generated opcodes as well as confirming the [manually provided ones](/book/structs-and-messages#message-opcodes). For example: ```md -## Deploy +### Deploy TL-B: `deploy#946a98b6 queryId:uint64 = Deploy` Signature: `Deploy{queryId:uint64}` -## Seven +### Seven TL-B: `seven#00000007 = Seven` Signature: `Seven{}` ``` From dd98e94fa1033c52ef10efc05760c61af3d88d64 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Tue, 14 Jan 2025 06:32:46 +0100 Subject: [PATCH 4/6] not a Tact signature, strictly speaking --- docs/src/content/docs/book/compile.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx index 9e5725d8c..829039bde 100644 --- a/docs/src/content/docs/book/compile.mdx +++ b/docs/src/content/docs/book/compile.mdx @@ -38,7 +38,7 @@ The following sub-headings describe the respective sections of the `.md` report. The first section introduces the present structures, i.e. some of the [composite types](/book/types#composite-types), [Structs and Messages](/book/structs-and-messages) that are declared or imported directly in the contract code, as well as those exposed from the Core standard library. -Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and Tact signatures. +Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and signatures. For example: From 9a1944cd37d349ff4fa2a507b6fcef04b2371237 Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:18:28 +0100 Subject: [PATCH 5/6] fix: suggestions from the code review --- docs/src/content/docs/book/compile.mdx | 31 ++++++++++++------- docs/src/content/docs/book/exit-codes.mdx | 2 +- .../docs/book/structs-and-messages.mdx | 6 +++- src/generator/writeReport.ts | 2 +- 4 files changed, 27 insertions(+), 14 deletions(-) diff --git a/docs/src/content/docs/book/compile.mdx b/docs/src/content/docs/book/compile.mdx index 829039bde..0c214b0fd 100644 --- a/docs/src/content/docs/book/compile.mdx +++ b/docs/src/content/docs/book/compile.mdx @@ -38,7 +38,7 @@ The following sub-headings describe the respective sections of the `.md` report. The first section introduces the present structures, i.e. some of the [composite types](/book/types#composite-types), [Structs and Messages](/book/structs-and-messages) that are declared or imported directly in the contract code, as well as those exposed from the Core standard library. -Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective [TL-B schemas][tlb] and signatures. +Along with the number of structures present, each of the [Structs][struct] and [Messages][message] are described with their respective signatures and [TL-B schemas][tlb], which include the [message opcodes](/book/structs-and-messages#message-opcodes). For example: @@ -49,25 +49,34 @@ Total structures: 10 TL-B: `_ code:^cell data:^cell = StateInit` Signature: `StateInit{code:^cell,data:^cell}` -### StdAddress -TL-B: `_ workchain:int8 address:uint256 = StdAddress` -Signature: `StdAddress{workchain:int8,address:uint256}` +### Deploy +TL-B: `deploy#946a98b6 queryId:uint64 = Deploy` +Signature: `Deploy{queryId:uint64}` ...etc. ``` -[TL-B schema][tlb] of each [Message][message] contains its opcode, which is handy for looking up the auto-generated opcodes as well as confirming the [manually provided ones](/book/structs-and-messages#message-opcodes). For example: +[TL-B schema][tlb] of each [Message][message] contains its opcode, which is handy for looking up the auto-generated opcodes as well as confirming the [manually provided ones](/book/structs-and-messages#message-opcodes). For example, the following [Message][message] declarations: + +```tact +message GeneratedOpcode { } +message(0x12345678) ManuallySpecifiedOpcode { } +``` + +translate to their respective [TL-B schemas][tlb]: ```md -### Deploy -TL-B: `deploy#946a98b6 queryId:uint64 = Deploy` -Signature: `Deploy{queryId:uint64}` +### GeneratedOpcode +TL-B: `generated_opcode#6dfea180 = GeneratedOpcode` +Signature: `GeneratedOpcode{}` -### Seven -TL-B: `seven#00000007 = Seven` -Signature: `Seven{}` +### ManuallySpecifiedOpcode +TL-B: `manually_specified_opcode#12345678 = ManuallySpecifiedOpcode` +Signature: `ManuallySpecifiedOpcode{}` ``` +where `6dfea180` and `12345678` specified after the `#` in the [constructor definitions](https://docs.ton.org/v3/documentation/data-formats/tlb/tl-b-language#constructors) are opcodes written in hexadecimal notation, representing $32$-bit unsigned integers. Thus, the automatically generated `6dfea180` opcode of the `GeneratedOpcode{:tact}` [Message][message] represents the decimal value of $1845404032$, and the manually provided `12345678` opcode of the `ManuallySpecifiedOpcode{:tact}` [Message][message] represents the decimal value of $305419896$, and **not** $12345678$ as it might appear. + #### Get methods {#getters} This section specifies the number of available get methods or [getter functions](/book/functions#getter-functions) and outlines them with their argument names, if any. diff --git a/docs/src/content/docs/book/exit-codes.mdx b/docs/src/content/docs/book/exit-codes.mdx index d00c141b5..0e1b97a5b 100644 --- a/docs/src/content/docs/book/exit-codes.mdx +++ b/docs/src/content/docs/book/exit-codes.mdx @@ -21,7 +21,7 @@ The range from $256$ to $65535$ is free for developer-defined exit codes. ## Table of exit codes {#table} -The following table lists exit codes with an origin (where it can occur) and a short description for each. The table doesn't list the exit code of the [`require()`](/ref/core-debug#require), as it generates it depending on the concrete `error` message [String][p]. +The following table lists exit codes with an origin (where it can occur) and a short description for each. The table doesn't list the exit code of the [`require()`](/ref/core-debug#require), as it generates it depending on the concrete `error` message [String][p]. To see such exit codes, refer to the [Exit codes section of the compilation report](/book/compile#exit-codes). Exit code | Origin | Brief description :------------ | :---------------------------------- | :---------------- diff --git a/docs/src/content/docs/book/structs-and-messages.mdx b/docs/src/content/docs/book/structs-and-messages.mdx index e173c3337..03bbbbb09 100644 --- a/docs/src/content/docs/book/structs-and-messages.mdx +++ b/docs/src/content/docs/book/structs-and-messages.mdx @@ -7,6 +7,8 @@ import { Badge } from '@astrojs/starlight/components'; Tact supports a number of [primitive data types](/book/types#primitive-types) that are tailored for smart contract use. However, using individual means of storage often becomes cumbersome, so there are [Structs](#structs) and [Messages](#messages) which allow combining types together. +After a successful compilation, Tact produces a [compilation report](/book/compile), which features all the declared [Structs](#structs) and [Messages](#messages), including those from the Core standard library. See the [Structures section of the compilation report](/book/compile#structures) for details. + :::caution **Warning**: 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**. @@ -107,7 +109,9 @@ message Add { Messages are almost the same thing as [Structs](#structs) with the only difference that Messages have a 32-bit integer header in their serialization containing their unique numeric id, commonly referred to as an _opcode_ (operation code). This allows Messages to be used with [receivers](/book/receive) since the contract can tell different types of messages apart based on this id. -Tact automatically generates those unique ids (opcodes) for every received Message, but this can be manually overwritten: +Tact automatically generates those unique ids (opcodes) for every received Message, which can be observed in the [Structures section of the compilation report](/book/compile#structures). + +Besides, opcodes can be overwritten manually: ```tact // This Message overwrites its unique id (opcode) with 0x7362d09c diff --git a/src/generator/writeReport.ts b/src/generator/writeReport.ts index 20238b737..1a51d49cc 100644 --- a/src/generator/writeReport.ts +++ b/src/generator/writeReport.ts @@ -37,7 +37,7 @@ export function writeReport(ctx: CompilerContext, pkg: PackageFileFormat) { for (const t of abi.getters!) { w.write(`## ${t.name}`); if (t.arguments!.length === 0) { - w.write(`This getter has no arguments`); + w.write(`No arguments`); } else { for (const arg of t.arguments!) { w.write(`Argument: ${arg.name}`); From b278f85fbef51c8931227002a8e01b908747c29f Mon Sep 17 00:00:00 2001 From: Novus Nota <68142933+novusnota@users.noreply.github.com> Date: Thu, 16 Jan 2025 14:19:27 +0100 Subject: [PATCH 6/6] fix: correction of the `queryId` description This didn't warrant a separate issue, but was important to do as pointed out in Tact chat --- docs/src/content/docs/book/cells.mdx | 24 ++++++++++++++-------- docs/src/content/docs/cookbook/jettons.mdx | 16 +++++++++++---- 2 files changed, 28 insertions(+), 12 deletions(-) diff --git a/docs/src/content/docs/book/cells.mdx b/docs/src/content/docs/book/cells.mdx index 9e5e5cb9a..719e1b835 100644 --- a/docs/src/content/docs/book/cells.mdx +++ b/docs/src/content/docs/book/cells.mdx @@ -178,14 +178,22 @@ contract SerializationExample { There, `^cell`, `^builder` and `^slice` in [TL-B][tlb] syntax mean the reference to [`Cell{:tact}`](#cells), [`Builder{:tact}`](#builders) and [`Slice{:tact}`](#slices) values respectively, while the `remainder<…>` of `cell`, `builder` or `slice` tells that the given value would be stored as a `Slice{:tact}` directly and not as a reference. -Now, to give a real-world example, imagine that you need to notice and react to inbound [jetton][jetton] transfers in your smart contract. The appropriate [Message][message] structure for doing so would look something like this: +Now, to give a real-world example, imagine that you need to notice and react to inbound [Jetton][jetton] transfers in your smart contract. The appropriate [Message][message] structure for doing so would look like this: ```tact /remaining/ message(0x7362d09c) JettonTransferNotification { - queryId: Int as uint64; // arbitrary request number to prevent replay attacks - amount: Int as coins; // amount of jettons transferred - sender: Address; // address of the sender of the jettons - forwardPayload: Slice as remaining; // optional custom payload + // Unique identifier used to trace transactions across multiple contracts + // Defaults to 0, which means we don't mark messages to trace their chains + queryId: Int as uint64 = 0; + + // Amount of Jettons transferred + amount: Int as coins; + + // Address of the sender of the Jettons + sender: Address; + + // Optional custom payload + forwardPayload: Slice as remaining; } ``` @@ -197,9 +205,9 @@ receive(msg: JettonTransferNotification) { } ``` -Upon receiving a [jetton][jetton] transfer notification message, its cell body is converted into a [`Slice{:tact}`](#slices) and then parsed as a `JettonTransferNotification{:tact}` [Message][message]. At the end of this process, the `forwardPayload` will have all the remaining data of the original message cell. +Upon receiving a [Jetton][jetton] transfer notification message, its cell body is converted into a [`Slice{:tact}`](#slices) and then parsed as a `JettonTransferNotification{:tact}` [Message][message]. At the end of this process, the `forwardPayload` will have all the remaining data of the original message cell. -Here, it's not possible to violate the [jetton][jetton] standard by placing the `forwardPayload: Slice as remaining` field in any other position in the `JettonTransferNotification{:tact}` [Message][message]. That's because Tact prohibits usage of `as remaining{:tact}` for any but the last field of the [Structs][struct] and [Messages][message] to prevent misuse of the contract storage and reduce gas consumption. +Here, it's not possible to violate the [Jetton][jetton] standard by placing the `forwardPayload: Slice as remaining` field in any other position in the `JettonTransferNotification{:tact}` [Message][message]. That's because Tact prohibits usage of `as remaining{:tact}` for any but the last field of the [Structs][struct] and [Messages][message] to prevent misuse of the contract storage and reduce gas consumption. :::note @@ -436,10 +444,10 @@ let areSlicesNotEqual = aSlice.hash() != bSlice.hash(); // false [struct]: /book/structs-and-messages#structs [message]: /book/structs-and-messages#messages [recv]: /book/contracts#receiver-functions +[jetton]: /cookbook/jettons [tvm]: https://docs.ton.org/learn/tvm-instructions/tvm-overview [tlb]: https://docs.ton.org/develop/data-formats/tl-b-language -[jetton]: https://docs.ton.org/develop/dapps/asset-processing/jettons [sha-2]: https://en.wikipedia.org/wiki/SHA-2#Hash_standard [quadtree]: https://en.wikipedia.org/wiki/Quadtree diff --git a/docs/src/content/docs/cookbook/jettons.mdx b/docs/src/content/docs/cookbook/jettons.mdx index 9ca6204ce..919acf9a7 100644 --- a/docs/src/content/docs/cookbook/jettons.mdx +++ b/docs/src/content/docs/cookbook/jettons.mdx @@ -40,13 +40,21 @@ Common examples of working with Jettons. ### Accepting Jetton transfer -Transfer notification message have the following structure. +Transfer notification message have the following structure: ```tact message(0x7362d09c) JettonTransferNotification { - queryId: Int as uint64; + // Unique identifier used to trace transactions across multiple contracts + // Defaults to 0, which means we don't mark messages to trace their chains + queryId: Int as uint64 = 0; + + // Amount of Jettons transferred amount: Int as coins; + + // Address of the sender of the Jettons sender: Address; + + // Optional custom payload forwardPayload: Slice as remaining; } ``` @@ -216,7 +224,7 @@ contract Example with Deployable { to: self.myJettonWalletAddress, value: JettonTransferGas, body: JettonTransfer{ - // To prevent replay attacks + // Unique identifier used to trace transactions across multiple contracts queryId: 42, // Jetton amount to transfer amount: msg.amount, @@ -311,7 +319,7 @@ contract Example with Deployable { to: self.myJettonWalletAddress, value: JettonBurnGas, body: JettonBurn{ - // To prevent replay attacks + // Unique identifier used to trace transactions across multiple contracts queryId: 42, // Jetton amount you want to burn amount: msg.amount,