TON Cookbook

[Hiyorimi]

Summary

TON might benefit from getting a cookbook with clear recipes for solving some common tasks.

Context

Cookbooks are common in software development: these are collections of actionable and practical tips & tricks on how to execute certain concepts. This question on Quora contains a great explanation of what cookbook is.

Regarding the blockchain there are a couple of good examples: Ethereum and Solana ones.

Inspiration: examples from the community

To understand which exactly FunC examples developers need was launched a feedback form in google document for everyone from the community:

https://docs.google.com/document/d/1l5865CZ2IzjD1r054rYPaPkNCBaUVVt2iEy9bWJGZqA/edit#

Everyone is welcome! If you don't see necessary things just add them to the list.

Goals

• Deliver TON cookbook containing recipes on the questions which are frequently asked by the community

Deliverables

• To write examples, you should decide where to write them. We provided a page in the TON Documentation for that:

https://ton.org/docs/develop/func/cookbook

Definition of Done

• Any junior developer without prior blockchain development experience is able to get quick onboarding to TON
• Any junior developer is able to set up TON developer environment and submit a hello world contract

Reward

• Standard TON Footsteps NFT

Basic examples

Total: $1225 for 49 examples

Advanced examples

Total: $450 for 9 examples

Important

• 25 USD (50 USD for advanced examples) equivalent in TON for every high-quality func example covered from the initial list.

How to participate?

• Please, respond to this message with a list of examples you want to cover, so I'll add you as assigned to them

[tsivarev]

We need to discuss the difference between ton.org/docs and a separate cookbook.

[liketurbo]

We need to discuss the difference between ton.org/docs and a separate cookbook.

In analogy with Rust, I see it as:

Official Rust book - ton.org/docs
Unofficial Rust cookbook - ton.org/cookbook

[Hiyorimi]

@liketurbo do you want to take a look at this?

[liketurbo]

@liketurbo do you want to take a look at this?

I don't have enough experience with FunC for that

[Gusarich]

I think it'll be the same as adding more examples in current docs?

[SwiftAdviser]

Cookbook update

With time, it became obvious that TON needed a Cookbook focused on smart contract development with FunC.

It's time to create a FunC Cookbook!

Content: examples from the community

To understand which exactly FunC examples developers need was launched a feedback form in google document for everyone from the community:

• https://docs.google.com/document/d/1l5865CZ2IzjD1r054rYPaPkNCBaUVVt2iEy9bWJGZqA/edit#

Everyone is welcome! If you don't see necessary things just add them to the list.

Platform: where add examples

To write examples, you should decide where to write them. I provide a page in the TON Documentation for that:

• https://ton.org/docs/develop/func/cookbook

Repository of ton-docs: https://github.com/ton-community/ton-docs

Reward

• I would suggest providing $25 for every high-quality func example covered from the initial list.
• Minimum of 10 examples needed to receive payment

How to participate?

Please, respond to this message with a list of examples you want to cover, so I'll add you as assigned to them

[Gusarich]

@SwiftAdviser I would like to cover these examples:
How to send a simple message
How to send a message with an incoming account
How to send a message with the entire balance
How to contain a data to cell (How to assign data to a cell (?))
How to contain a data to cell which size more than 1023 bits (sending a comment as an internal message) (How to assign data to a cell no more than 1023 bits in size(?))
How to ignore refs move only bits from slice to builder
How to make your own function for operator ~
How to iterate dicts (by index, get delete min, get delete max)
How to iterate cells by bits and refs
How to read a state of the contract if it is empty

But I want to clarify what exactly is meant in those examples that I have marked in italics. @SwiftAdviser can you explain those in more details?

How to send a message with an incoming account
— do you mean sending a message to address from which the incoming msg was received?

How to contain a data to cell (How to assign data to a cell (?))
How to contain a data to cell which size more than 1023 bits (sending a comment as an internal message) (How to assign data to a cell no more than 1023 bits in size(?))
— which data? if it's something we want to store in a cell, it's probably already a slice/builder and storing these to cell is pretty obvious. and if it's some other type (like a tuple), the way for storing it in a cell can differ depending on the exact case.

How to iterate cells by bits and refs
— do you mean just iterating through <=1023 bits and <=4 refs of some single cell, or recursively iterating through the whole tree?

How to read a state of the contract if it is empty
— what do you want to read if it's empty? get_data() will just return an empty cell, so what's the problem?

[Hiyorimi]

Approved!

[Hiyorimi]

Updated the initial Footstep description after a chat with @SwiftAdviser

[Miandic]

Hi! I can cover these 12 examples:
How to determine a cell is empty
How to determine a slice is empty
How to determine a dict is empty
How to determine a tuple is empty
How to determine a state of the contract is empty
How to write an if statement (note that true is -1)
How to write a while statement
How to write a do until statement
How to build an internal message cell
How to contain a body as ref to an internal message cell
How to contain a body as slice to an internal message cell
How to iterate tuples (in both directions)

@Hiyorimi @SwiftAdviser can you confirm?

[SwiftAdviser]

want

Let's make a chat!

@Miandic, could you write to my Telegram: @SwiftAdviser? I'll add you to the chat too.

[liketurbo]

I can take lefties:

• How to send a deploy message (with stateInit only, with stateInit and body)
• How to build a stateInit cell
• How to calculate a contract address (using stateInit)
• How to build an external message cell (for a wallet contract maybe)
• How to build an external message which contains an internal message
• How to make an index storage using dict
• Prevent using global variables
• Prevent using an impure function (instead of sending messages and set store)
• How to handle a bounce when a transaction fails
• How to make a contract which will deployed after topup (proxy contract which send internal messages for addresses are specified in data init of contract)

[Gusarich]

@Miandic @liketurbo assigned you to this issue ;)

[Miandic]

I have covered my examples
ton-community/ton-docs#82

[miroslav-tashonov]

I can cover the following examples :

1. iterating n-nested tuple
2. resolving type X ( it can be all of supported types cell, slice, tuple, int etc )
3. reversing a tuple
4. multiplying, dividing, summing and intersect for two 256 numbers with modulo
5. how to determine if two slices are equal
6. how to determine if two cells are equal
7. how to determine if two tuples are equal
8. creating internal address or testing purposes
9. creating external address for testing purposes
10. how to store and load dictionary in local storage

[Gusarich]

I have covered my examples ton-community/ton-docs#82

@Miandic can you please open a PR in the footsteps repository and add yourself to the Hall of fame?

[mkl-]

@SwiftAdviser I would like to take:

1. Setting up dev-environment using VSCode and ton-contract-executor
2. FunC/JS interface
3. smart contract deployment

[tactfunc]

• How can we send the external message to TVM or any smart contract in there(Not an internal message)?
• How can we upgrade the contract from ContractA to ContractB, since we want to update the logic of the function (maybe in the same function name) but keep data the same?

[liketurbo]

• How can we send the external message to TVM or any smart contract in there(Not an internal message)?

• How can we upgrade the contract from ContractA to ContractB, since we want to update the logic of the function (maybe in the same function name) but keep data the same?

I think, there is already a one for external message ... and it's been and other ones assigned to me for a quite some time 😄
I don't think I'll be free to finish them anytime soon ... so I'd better to yield back, so a more responsible dev can take them 🙂

@Gusarich, here is the status list:

1. How to send a deploy message (with stateInit only, with stateInit and body)
2. How to build a stateInit cell
3. How to calculate a contract address (using stateInit)
4. How to build an external message cell (for a wallet contract maybe)
5. How to build an external message which contains an internal message
6. How to make an index storage using dict
7. Prevent using global variables
8. Prevent using an impure function (instead of sending messages and set store)
9. How to handle a bounce when a transaction fails
10. How to make a contract which will deployed after topup

Shortly, I will create PR

[howardpen9]

We need to draft content and examples for the Tact language, particularly to create "the Tact cookbook". This is because:

We need to address the practical issues that not everyone is able to work with FunC. To improve the developer experience, TON needs to onboard more developers.

From a marketing perspective, Tact is more similar to the "Rust language". This is a good selling point to attract "high-level" developers with experience in coding to migrate to TON or TVM network. We need to position Tact as a "Rust" alternative to ### attract developers who have worked on other blockchains such as Polkadots, Solana, and Cosmos, which use Rust as the main language for programming smart contracts.

This could be a good slogan. Data shows that more and more people are learning Rust over C.

For the long-term perspective, more developers mean more network effects for a technology. We understand how great FunC is, but we also understand the amount of time it takes to learn, which is why we need to position Tact as an alternative to Rust to attract more developers.

#143

[liketurbo]

We need to draft content and examples for the Tact language, particularly to create "the Tact cookbook". This is because:

We need to address the practical issues that not everyone is able to work with FunC. To improve the developer experience, TON needs to onboard more developers.

From a marketing perspective, Tact is more similar to the "Rust language". This is a good selling point to attract "high-level" developers with experience in coding to migrate to TON or TVM network. We need to position Tact as a "Rust" alternative to ### attract developers who have worked on other blockchains such as Polkadots, Solana, and Cosmos, which use Rust as the main language for programming smart contracts.

This could be a good slogan. Data shows that more and more people are learning Rust over C.

For the long-term perspective, more developers mean more network effects for a technology. We understand how great FunC is, but we also understand the amount of time it takes to learn, which is why we need to position Tact as an alternative to Rust to attract more developers.

#143

Wouldn't be then more reasonable to use Rust instead of "something like Rust" 😀
I'm sure it's feasible cause TonLabs did something similar for their TVM fork ...

[ghost]

@Hiyorimi is there any activity / tasks here?

[Gusarich]

Do we need any more examples? If no, let's close this issue

[delovoyhomie]

@SwiftAdviser, can we close this issue?

[delovoyhomie]

Thank you all for your contributions!

We really appreciate your initiatives, TON Cookbook will allow new developers to get used to it faster.

[Gusarich]

I suggest to add a few more examples on more deep things. Masterchain libraries, merkle proof/update cells, continuations.
These new examples will be rewarded with increased value due to their complexity and knowledge required. I suggest rewarding each of these examples as 50$.

[Gusarich]

I have came up with the following list of advanced examples:

• How to create a continuation using Fift
• How to execute a continuation using FunC
• How to deploy a library to masterchain
• How to use deployed library in smart contract
• How to deploy a smart contract with code taken from library
• How to generate Merkle proof for dictionary using ton TS library
• How to verify Merkle proof in a dictionary
• How to generate Merkle update for dictionary using ton TS library
• How to apply Merkle update to a dictionary

I would like to complete all of these. I'm working in this branch of ton-docs repository:

• https://github.com/ton-community/ton-docs/tree/update-cookbook

[delovoyhomie]

@SwiftAdviser, @Gusarich, are we completing the remaining two examples?

• How to deploy a library to masterchain
• How to deploy a smart contract with code taken from library

[Gusarich]

@delovoyhomie there are some troubles in @ton/core with deploying libraries. I think we can exclude these two examples and complete the merge with all other ones that are done already.
but note that we also need to wait until the merge of ton-org/ton-core#8 in order for other examples to be correct.

[delovoyhomie]

We close this issue until the problems are resolved in @ton/core.
As soon as the problems on the side of ton-org/ton-core#8 are solved, let's create a new bounty with examples of packs, for example, 10 pieces each.