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

• - Processing Snake Cells + 8 examples - tonweb @aSpite (325$)
• - Parsing transactions for basic operations - ton.js @Gusarich (50$)
• - Calculating a user's Jetton wallet address - ton-kotlin @LevZed - (25$)
• - Sending a standard TON transfer message - ton-kotlin @LevZed - (25$)
• - Sending a swap message to DEX(dedust) - ton-kotlin @LevZed - (100$)
• - Jetton transfer with a comment. pytoniq @shibdev - (25$)
• - Calculating a user’s Jetton wallet address. - pytoniq @shibdev - (25$)
• - Sending a standard TON transfer message. - pytoniq @shibdev - (25$)
• - Parsing transactions for basic operations - pytoniq @shibdev - (50$)
• - Sending a swap message to dedust.io - pytoniq @shibdev - (50$)
• - 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$)
• - 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: ton-community/ton-docs#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: ton-community/ton-docs#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!

[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

[reveloper]

@shibdev, great! reviewed and merged, thank you!

[shibdev]

@reveloper,

I would like to work on this examples:

• Parsing transactions for basic operations, recognize type (most common example provided). [hard] pytoniq
• Sending a swap message to DEX (e.g., ston.fi, dedust.io). [hard] pytoniq

[reveloper]

@shibdev,

Great! These two are assigned to you.

[shibdev]

@reveloper,

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

[reveloper]

@mbaneshi how is it going with examples, do you plan to finish this task?

[mbaneshi]

@reveloper, yes for sure. I am in the middle of doing it.

These days I am involved in tsc5 but soon it will be done.

[mbaneshi]

@reveloper , I sent a mbaneshi:patch-19

[mbaneshi]

@Gusarich
@reveloper
I fixed problem.

[reveloper]

@mbaneshi thank you, merged! In the task we have tonweb and ton.js. Do you plan to finish tonweb version for this example?
- Sending a swap message to DEX @mbaneshi - ton.js and tonweb - (100$)

[mbaneshi]

@reveloper , Yes , I am busy doing it . Just a question, what exactly processing swap message means? I am talking about second part of my assignment, as Dex just send simple message and charge and inform received address. I am wonder should I write a smart contract and ready to received such message or .. something else ? please let me know , thank you.

[reveloper]

@mbaneshi not a smart contract, but a wrapper that filter and parse this kind of transaction.

[mbaneshi]

Hello everyone,

I'm having some trouble with a tutorial on Tonweb swaps. I've completed the Ton.js setup and it's published, but I find the limited examples in Tonweb a bit challenging. Could someone here kindly assist me in figuring it out? I'd really appreciate your help. Thank you in advance!

[reveloper]

Missing new examples:
Highload wallet v3 wrappers:

• Rewrite withdraw jettons highload v3 batched [very hard] (~150$ for the first reimplementation)
• Rewrite withdraw toncoin highload v3 batched [very hard] (~150$ for the first reimplementation)

Added and completed by @aSpite - jetton offline calculation.

[reveloper]

Rewrite withdraw jettons highload v3 batched [very hard]
Rewrite withdraw toncoin highload v3 batched [very hard]

For Pythoniq assigned to @shibdev

[reveloper]

Hello everyone,

I'm having some trouble with a tutorial on Tonweb swaps. I've completed the Ton.js setup and it's published, but I find the limited examples in Tonweb a bit challenging. Could someone here kindly assist me in figuring it out? I'd really appreciate your help. Thank you in advance!

@mbaneshi You've finished the ton.js part for How to send a swap message to DEX (DeDust)?. I displayed your job in the list and you'll get a reward for the job you've done.

We'll try to find another assignee for this task (as you said, we need somebody who has related experience with Tonweb).
We want to show these examples to the community sooner.

[mbaneshi]

@reveloper , No problem.
Just for help new assignee, I can share my draft not finished work here

[Ikhsanmaulana121999]

Best projeck