TON Cookbook of Contract Wrappers

[reveloper]

Summary

This Bounty aims to make a TON Cookbook with clear examples and recipes for interacting with contracts using various TON libraries, specifically @ton.js and tonweb for the TWA and DApps section in the docs.ton.org documentation.

Ton Bounty was created with the help of @footsteps_helper_bot.

Wanted Designed and Applied

Description	Сomplexity	Libraries
Jetton transfer with a comment	easy	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin ,TonSDK.NET
Processing Snake Cells	easy	Tonweb
Sending a swap message to DEX (e.g., ston.fi, dedust.io).	hard	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin ,TonSDK.NET
Processing swap transactions from DEX (e.g., ston.fi, dedust.io).	very hard	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Providing a complete formula for fee calculation (simplest examples: transfer ton, transfer jetton).	hard	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Calculating a user’s Jetton wallet address.	easy	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Sending a standard TON transfer message.	easy	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Processing a standard TON transfer message.	easy	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Parsing transactions for basic operations, recognize type (most common example provided)	hard	Tonweb, ton.js, Pythoniq, tonutils, TonSDK.NET
(Low level) Parsing blockchain blocks.	hard	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Parsing dicts(jetton metadata and general case)	easy	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Calculate tx and msg hashes	easy	Tonweb, ton.js, Pythoniq, tonutils, ton-kotlin, TonSDK.NET
Rewrite withdraw jettons highload v3 batched Tonweb	very hard	Pythoniq, tonutils, ton4j
Rewrite withdraw ton highload v3 batched Tonweb	very hard	Pythoniq, tonutils, ton4j

Context

In the field of development, cookbooks are valuable resources that provide actionable tips and tricks for executing certain concepts. Unified examples of contract wrappers will make a smoother and easier learning and development process of TWAs and DApps in TON Ecosystem.

Goals

• Prepare examples for the TON Cookbook containing recipes that address frequently asked questions and common tasks related to interaction with a contract.

• Cover with examples all frequency and repeatable questions.

• Oriental Release Date: 2 weeks after the list of examples was approved.

• As an initial set of examples, the following groups of questions can be used:

  • "How to interact with <_type_> entity?"
  • "How to retrieve and use specific data for various get method of <_a specific generic or custom contract_>?"
  • "How to define the success of the incoming transactions for <_a specific generic or a custom contract_>?"
  • "How to deserialize and handle different messages"
    • Generic contracts are: Wallet, SBT, NFT, Jetton, DNS (could be added on recommendation)

• Examples should cover part, that was not explained in libraries examples: Tonweb or should be improved significantly to be considered as original examples based on this.

• Different libraries and languages for the same question should be shown with Tabs.

• Recommended libraries for JS languages:

  • ton JS
  • tonweb

• Recommended libraries for additional languages:

  • Python - pythoniq (low-level), Tontools (high-level);
  • Java - ton4j;
  • Kotlin - ton-kotlin;
  • GO - tonutils;
  • C# - TonSDK.NET

Deliverables

• Cookbook containing clear examples and recipes for using JS (ton JS and tonweb libraries) Python, GO, C# languages to interact with TON contracts.
• Simplified process of basic logic implementation for DApps and TWAs.

Definition of Done

• This footstep aims to create a useful cookbook for TON Ecosystem. For each participant award will be paid after PR with his examples will be merged to docs.ton.org.

For clearness of the moderation process, declare for each set of examples the following steps:

1. Participants declare a list of names and a brief description of examples(1-3 pcs)
2. The list of examples should be pre-reviewed briefly by an expert TON contributor and approve this list.
3. Participants create examples and add them with a PR to ton.docs.org.
4. Ready-made PR to docs with examples reviewed again by a tech expert.
   • @Gusarich (js)
   • @aSpite (js)
   • @andreypfau (Kotlin)
   • @yungwine (Python)

Estimated Reward

• [x] - Processing Snake Cells + 8 examples - tonweb @aSpite (325$)
• [x] - Parsing transactions for basic operations - ton.js @Gusarich (50$)
• [x] - Calculating a user's Jetton wallet address - ton-kotlin @LevZed - (25$)
• [x] - Sending a standard TON transfer message - ton-kotlin @LevZed - (25$)
• [x] - Sending a swap message to DEX(dedust) - ton-kotlin @LevZed - (100$)
• [x] - Jetton transfer with a comment. pytoniq @shibdev - (25$)
• [x] - Calculating a user’s Jetton wallet address. - pytoniq @shibdev - (25$)
• [x] - Sending a standard TON transfer message. - pytoniq @shibdev - (25$)
• [x] - Parsing transactions for basic operations - pytoniq @shibdev - (50$)
• [x] - Sending a swap message to dedust.io - pytoniq @shibdev - (50$)
• [x] - Offline jetton address calculation - @ton/ton @aSpite - (50$)
• [ ] - Rewrite withdraw ton highload v3 batched Tonweb - pytoniq @shibdev - (150$)
• [ ] - Rewrite withdraw jettons highload v3 batched Tonweb - pytoniq @shibdev - (150$)
• [x] - Sending a swap message to DEX @mbaneshi - ton.js - (50$)
• [ ] - Sending a swap message to DEX @??? - tonweb - (100$)
• [ ] - Processing swap transactions from DEX @??? ton.js and tonweb - (100$)

Reward Distribution Rules

• Successful completion of basic(easy) examples: $25 per example in TON equivalent.
• Successful completion of advanced examples(or using tonweb): $50 per example in TON equivalent.
• Successful completion of very hard examples - determined individually.
• The review compensation for reviewer experts at 10% of the reward for the examples

[AndreyBurnosov]

I'd like to participate

[Gusarich]

I can help with review if needed

[delovoyhomie]

Community, you can join too. The number of executors is not limited!

[reveloper]

@Gusarich, great! For me, it's hard to define the fair cost of review. Please, help to define ~oriental cost, it's also could be clarified later.

[aSpite]

@reveloper

The price is very high. It won't take an hour to write an example, even if it were something complex. I think it should be changed to 10 and 20. Or a maximum of 15 and 25. It should be borne in mind that many examples are already in the documentation.

UPD: If the examples are detailed, understandable and of high quality, then such a price is justified. I would like to help with the review, if possible.

[reveloper]

@aSpite great, added you to expert list. Thank you!

@AndreyBurnosov would you provide the example list you want to prepare?

[AndreyBurnosov]

I haven't thought about this question yet, what kind of examples are needed? @reveloper

[aSpite]

@AndreyBurnosov

Each participant can propose a list of examples they would like to explore. These examples can encompass various types of operations and transactions, taking into account the demand.

For instance, you can consider how to parse Jetton metadata using the ton.js library. It's important to consider that this metadata can be off-chain, semi-chain, or on-chain. Therefore, it's necessary to deeply examine each example to provide a highly unique case that would be applicable in the majority of scenarios.

There is a demand within the community for such examples. For instance, a developer might want to send a token with a comment, but they might not understand how to do it. A high-quality Cookbook should address this issue within a minute.

Important: I am not the author of the footstep, so my words are merely a recommendation. @reveloper could provide a more precise answer.

[reveloper]

Due to nobody finding this footstep(ton-bounty) interesting at the moment, I asked @aSpite to help us with examples as a participant. I personally asked for 3 examples about addresses(2) and jetton transfer(1), because this is what I need for everyday work.

Dear @Gusarich, We count on your expertise for review.

[aSpite]

1. How to convert (user friendly <-> raw), assemble, and extract addresses from strings? (JS, Python, Go) - Hard (if all languages at once)
2. How to obtain different types of addresses (bounceable, non-bounceable, testnet) and determine the address type based on its user-friendly form? - Hard (if all languages at once)
3. How to construct a message for a jetton transfer with a comment? - Easy (ton.js)
4. How to use NFT batch deploy? - Hard (ton.js)
5. How to change the owner of a collection's smart contract? - Easy (ton.js)
6. How to change the content in a collection's smart contract? - Hard (ton.js)

[reveloper]

Great, @aSpite, I confirm this list, please prepare the PR.

[aSpite]

@Gusarich , @reveloper ,

My examples are ready. PR: https://github.com/ton-community/ton-docs/pull/343

[reveloper]

Dear community!

I suggest the following examples:

• Sending a swap message to DEX (e.g., ston.fi, dedust.io). [hard for the first library]
• Processing swap transactions from DEX (e.g., ston.fi, dedust.io). [hard for the first library]
• Providing a complete formula for fee calculation (simplest examples: transfer ton, transfer jetton). [hard]
• Calculating a user’s Jetton wallet address. [easy]
• Sending a standard TON transfer message. [easy]
• Processing a standard TON transfer message. [easy]
• (High level) Parsing transactions for basic operations, recognize type (most common example provided) [hard]
• (Low level) Parsing blockchain blocks. [hard]
• Parsing dicts(jetton metadata and general case)

I kindly remind you to implement examples for ton.js in the first order where this is possible.

[reveloper]

I added clarification about recommended libraries in the description of ton bounty.

Recommended libraries for additional languages:

Python - pythoniq-core (low-level), Tontools (high-level); GO - tonutils; C# - TonSDK.NET

[aSpite]

@reveloper ,

How to construct a message for a jetton transfer with a comment? - Easy (tonweb)

As 1 easy example: How to change the owner of a collection's smart contract? - Easy (tonweb) How to change the content in a collection's smart contract? - Easy (tonweb)

[aSpite]

@Gusarich , @reveloper

Tonweb examples are ready: https://github.com/ton-community/ton-docs/pull/347

[coalus]

@reveloper,

I would like to work on this examples:

• Calculating a user’s Jetton wallet address. [easy] ton.js
• Sending a standard TON transfer message. [easy] ton.js
• Sending a swap message to DEX (e.g., ston.fi, dedust.io). [hard for the first library] ton.js

[reveloper]

@coalus, great! Do you mean ton.js library? Please, add library name in the your list.

[aSpite]

1st Iteration: 4 hard at $50 each, which equals $200. 2 easy at $25 each, which equals $50. Total: 250$

2nd Iteration: 2 easy at $25 each, which equals $50. Tonweb examples.

Total: 300$ Wallet: EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF

The cookbook already has enough examples to understand how they should be done. Therefore, the next contributors can continue without major issues. I would like to continue my work as a reviewer, if it possible, @reveloper .

[reveloper]

@aSpite, sure, thank you! Will count on your help with the review.

@coalus, OK, now your list is confirmed.

[Gusarich]

@Gusarich, great! For me, it's hard to define the fair cost of review. Please, help to define ~oriental cost, it's also could be clarified later.

The review didn't take much time, so I'll be happy with 50$ and TON Footsteps SBT 🙂 My wallet address: sedov.t.me

[delovoyhomie]

@Gusarich, let's set the review reward at 10% of the reward for the examples. This will be fair in terms of effort: more complex ones require more effort, and thus merit a bigger reward.

So, for 8 examples from @aSpite valued at $300, we would be pleased to thank you with 10% = $30 + TON Footsteps SBT.

[Gusarich]

@Gusarich, let's set the review reward at 10% of the reward for the examples. This will be fair in terms of effort: more complex ones require more effort, and thus merit a bigger reward.

So, for 8 examples from @aSpite valued at $300, we would be pleased to thank you with 10% = $30 + TON Footsteps SBT.

Sure!

[aSpite]

@Gusarich, let's set the review reward at 10% of the reward for the examples. This will be fair in terms of effort: more complex ones require more effort, and thus merit a bigger reward.

So, for 8 examples from @aSpite valued at $300, we would be pleased to thank you with 10% = $30 + TON Footsteps SBT.

I would like to clarify something. The review process requires not only checking the text but also running and thoroughly testing the execution of the provided examples. For instance, if the example is "batch deploy," the reviewer needs to create a test collection and deploy the NFT. This should all happen quite quickly if the person who wrote the example did everything initially with few errors. Otherwise, the review process may take even more time, considering that each new correction requires reevaluating the code from scratch.

[aSpite]

@reveloper ,

I also want to propose a deadline for each new iteration. Otherwise, it's possible that some examples may be delayed for a week.

For example, if it's about changing the owner of a collection, that should take a maximum of 2-3 hours, so the example should be ready within a maximum of 2 days.

[coalus]

@reveloper, is it possible to use dedust sdk to write dex swap example?

[aSpite]

@coalus ,

I would personally rather not use the Dedust SDK for a few reasons:

1. The SDK already has the needed wrappers and doesn't need a total revamp. It also includes documentation, so it's not hard to work with.
2. We not only have Dedust but also Ston.fi, which requires us to provide an example.
3. The SDK is only available in JS/TS, so for other languages, we'll need different examples, but they should be as similar as possible.

However, the final decision ultimately belongs to @reveloper .

[coalus]

@coalus ,

I would personally rather not use the Dedust SDK for a few reasons:

1. The SDK already has the needed wrappers and doesn't need a total revamp. It also includes documentation, so it's not hard to work with.
2. We not only have Dedust but also Ston.fi, which requires us to provide an example.
3. The SDK is only available in JS/TS, so for other languages, we'll need different examples, but they should be as similar as possible.

However, the final decision ultimately belongs to @reveloper .

1. We can just change status of this task from "hard" to "easy"
2. Ston.fi also have their own sdk
3. There are already implementation on Python. Most of the products on TON use one of this languages.

My point is that if someone wants to add dedust/ston.fi swap support to their product, it's a bit better to use SDK.

[aSpite]

@coalus , I would personally rather not use the Dedust SDK for a few reasons:

1. The SDK already has the needed wrappers and doesn't need a total revamp. It also includes documentation, so it's not hard to work with.
2. We not only have Dedust but also Ston.fi, which requires us to provide an example.
3. The SDK is only available in JS/TS, so for other languages, we'll need different examples, but they should be as similar as possible.

However, the final decision ultimately belongs to @reveloper .

1. We can just change status of this task from "hard" to "easy"
2. Ston.fi also have their own sdk
3. There are already implementation on Python. Most of the products on TON use one of this languages.

My point is that if someone wants to add dedust/ston.fi swap support to their product, it's a bit better to use SDK.

I looked at the Dedust SDK code. There is quite a lot of code and processing details, so I agree that using the SDK would be better. In this case, I would also show the use of the SDK for Ston.fi and leave the task as hard.

@reveloper

[reveloper]

@ Missing the example: "How to put on sale telemint NFTs: nft-item-no-dns and nft-item".

I suppose it will be easy because it simple enough message with a payload.

[reveloper]

@aSpite Sorry for the late answer, I was on vacation. I will add "Oriental Release Date" in the description which equals 2 weeks.

The idea of create processing examples for different contracts, so it is not about avoiding the SDK. Anyway, different teams have to face such tasks, that's why I placed this on the list. Of course, we can omit if this looks too expensive and does not fit to format of the TON Cookbook.

@coalus I'll add context on this: There are already implementation on Python. Most of the products on TON use one of these languages. - developers who are faced with such tasks have to reimplement this because SDKs support only very basic logic while they need to describe a lot of unique custom logic. Of course, we can say that of request each of SDKs could be extended with time based on request.

However, big commercial product teams prefer just to do their own solution as it is faster(and cheaper). Their main request after all is to see as many as possible different examples of interaction with smart contracts.

[aSpite]

@reveloper, I would like to take this example:

Processing Snake Cells (tonweb)

[reveloper]

@aSpite, yes, we need this example for developers, I got question related to this algorithm.

[aSpite]

@reveloper, the example is ready: https://github.com/ton-community/ton-docs/pull/417

[reveloper]

@mbaneshi, please, specify which one example you want to cover.

[reveloper]

@mbaneshi, If you wish to participate in this bounty, please specify the exact name of the example you intend to prepare(check the table in the beginning), along with the libraries you plan to cover.

While it is preferable to focus on tonweb/tonjs initially, starting with a different language is also permissible.

[mbaneshi]

I choose 'Sending a swap message to DEX (e.g., ston.fi, dedust.io)' and 'Processing swap transactions from DEX (e.g., ston.fi, dedust.io)' utilizing tonweb/tonjs. It should be mentioned that I ask for triple the suggested timeframe because I anticipate there are many concepts and protocols to be digested in the first place. Also, I appreciate someone who accepts mentorship. Please bear with newcomers.

[reveloper]

@mbaneshi, great! For sure, you can spend more time to research this. It is great if you learn something useful for yourself and share this with developers at the same time.

Please, specify how much time you estimated to spend on this for clearness ( weeks?). Also, please, declare the library you want to cover.

[mbaneshi]

@reveloper I plan to cover both library, maybe even compare in detail and contribute to them as well. While I do my best to conduct task as soon as possible,yet as mentioned before most upper bound would be 6 weeks. For sure I like to share my learning journey and I will do that. I guess a blog post comes out.

[reveloper]

@mbaneshi, sure, take your time.

Could you please specify the libraries you're referring to? Are they 'ton.js' and 'tonweb'?

[reveloper]

@mbaneshi

No, just wanted to double-check which libraries you called both. Awesome!

TON community looking forward to your contribution!

[reveloper]

@delovoyhomie I have an urgent request and asked @Gusarich personally to create an example for parsing transactions with the @ton/ton library, because nobody has volunteered for this task and we need this example ASAP.

Parsing transactions for basic operations, recognize type (most common example provided) - ton.js

[LevZed]

Hi @reveloper, I'd like to do two easy examples with Kotlin:

• Calculating a user's Jetton wallet address.
• Sending a standard TON transfer message.

[reveloper]

@LevZed great, assigned for you. We are looking forward to your PR for Kotlin!

[LevZed]

@reveloper, while first 2 examples on review, I'd like to take

• Sending a swap message to DEX (e.g., ston.fi, dedust.io) (ton-kotlin)

[reveloper]

@LevZed sure, take care of this one. Thank you!

[delovoyhomie]

@aspite, rewards sent!

• https://tonscan.org/tx/Z5seMmPVq9HpR1zKQYxJ06WoiWsKeivTpbtYN1e6HfE=
• Questbook proposal

To accurately recognize your valuable contributions in our repository, we kindly request you to submit a Pull Request to the Hall of Fame file, providing the wallet address and a link to the bounty with the number.

Please follow these steps: 1) Fork the repository (if you haven't already). 2) Edit the Hall of Fame file, commit, and push your changes. 3) Create a Pull Request from your fork to the main repository, providing the wallet address and a link to the bounty with the number (for example, Pull Request https://github.com/ton-society/grants-and-bounties/pull/136).

For reference on what your entry should look like, please see the examples of past merged pull requests.

Thank you for your contribution!

[shibdev]

@reveloper ,

I would like to work on this examples:

• Jetton transfer with a comment. [easy] pytoniq
• Calculating a user’s Jetton wallet address. [easy] pytoniq
• Sending a standard TON transfer message. [easy] pytoniq

[reveloper]

@shibdev, great! Assigned to you!

[shibdev]

@reveloper ,

Pytoniq examples are ready: ton-community/ton-docs/pull/440