You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/develop/dapps/asset-processing/README.md
+15-13Lines changed: 15 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -8,30 +8,32 @@ This page contains an overview and specific details that explain how to process
8
8
TON transactions are irreversible after just one confirmation. For the best user experience, it is suggested to avoid waiting on additional blocks once transactions are finalized on the TON Blockchain. Read more in the [Catchain.pdf](https://docs.ton.org/catchain.pdf#page=3).
9
9
:::
10
10
11
-
Best practices with comments on Toncoin processing:
11
+
## Best Practices
12
+
13
+
#### Fundamentals Examples
12
14
13
15
-[Create a key pair, a wallet and get a wallet address](https://github.com/toncenter/examples/blob/main/common.js)
14
16
15
-
-[JS code to accept Toncoin deposits](https://github.com/toncenter/examples/blob/main/deposits.js)
16
-
:::info
17
-
It is suggested to accept deposits across multiple wallets.
18
-
:::
17
+
-[JS code batch for the sending Toncoin](https://github.com/toncenter/examples/blob/main/withdrawals-highload-batch.js)
19
18
19
+
#### Toncoin Deposits and Withdrawals
20
20
21
-
-[JS code to withdraw (send) Toncoins from a wallet](https://github.com/toncenter/examples/blob/main/withdrawals-highload.js)
21
+
:::info
22
+
It is suggested to accept deposits across multiple wallets on your side.
23
+
:::
22
24
25
+
-[JS code to accept Toncoin deposits](https://github.com/toncenter/examples/blob/main/deposits.js)
26
+
-[JS code to withdraw (send) Toncoins from a wallet](https://github.com/toncenter/examples/blob/main/withdrawals-highload.js)
Copy file name to clipboardExpand all lines: docs/develop/data-formats/library-cells.md
+29-14Lines changed: 29 additions & 14 deletions
Original file line number
Diff line number
Diff line change
@@ -3,41 +3,50 @@
3
3
## Introduction
4
4
One of the native feature of how TON stores data in Cells is deduplication: in storage, messages, blocks, transactions and so on duplicate cells are stored only once. This tremendously decrease size of serialized data, and allows efficient storage of step-wise updated data.
5
5
6
-
For instance, lets consider basechain step from block 1'000'000 to block 1'000'001. While each block contains small amount of data (usually less than 1000 transactions), whole basechain state contains millions of accounts and since blockchain need to keep integrity of the data (in particular to commit merkle root hash of whole state to the block) whole tree of the state need to be updated. In previous generation blockchains it means that generally you keep track of only recent states because storing separate chain states for each block will require too much space. But not in TON: due to deduplication, for each block you only add to storage new cells. This not only make processing faster but also allows you to efficiently work with history: check balances, states and even run getmethods for any point in history without much overhead!
7
-
8
6
For the same reason many structures in TON are simultaneously rich, convinient and efficient: block structure contains the same copy of each message in many places: in Message queue, in list of Transaction, in Merkle updates and so on: since duplication has no overhead we can store data multiple times where we need it without worring about efficiency.
9
7
8
+
Library cells employ a deduplication mechanism on-chain, allowing the integration of this technology into custom smart contracts.
10
9
:::info
11
10
If you store jetton-wallet code as library cell (1 cell and 256+8 bits, instead of ~20 cells and 6000 bits) for instance, forward fees for a message that contains `init_code` will be decreased from 0.011 to 0.003 TON.
12
11
:::
13
12
14
13
## General Info
15
14
16
-
So, when we have a family of similar contracts (for instance jetton-wallets), node stores duplicating data (the same code of each jetton-wallet) only once. There is special mechanism how developers may utilize this deduplication mechanism to decrease storage and forward fees. This mechanism is called Library Cells.
15
+
Lets consider basechain step from block 1'000'000 to block 1'000'001. While each block contains small amount of data (usually less than 1000 transactions), the whole Basechain state contains millions of accounts and since blockchain need to keep integrity of the data (in particular to commit merkle root hash of whole state to the block) whole tree of the state need to be updated.
16
+
17
+
For the blockchains of previous generations this means that generally you keep track of only recent states because storing separate chain states for each block will require too much space. But in TON Blockchain due to deduplication, for each block you only add to storage new cells. This not only make processing faster but also allows you to efficiently work with history: check balances, states and even run getmethods for any point in history without much overhead!
18
+
19
+
For the case when we have a family of similar contracts (for instance jetton-wallets), node stores duplicating data (the same code of each jetton-wallet) only once. Library Cells allows to utilize deduplication mechanism for such contracts to decrease storage and forward fees.
17
20
18
21
:::info Highlevel analogy
19
22
You can consider library cell as C++ pointer: one small cell that points to larger Cell with (possibly) many refs. The referenced cell (cell to which library cell points) should exist and registered in public context (_"published"_).
20
23
:::
21
24
22
-
Library cell is [exotic cell](/develop/data-formats/exotic-cells) that contains a reference to some other static cell. In particular it contains 256 bit of hash of referenced cell. For TVM library cells works as follows: whenever TVM gets command to open cell to slice (opcode `CTOS`, funC `.begin_parse()`), it searches cell with hash from library cell in masterchain library context and if found open referenced cell and return it's slice. Opening library cell costs the same as opening ordinar cell, so it can be used as transparent replacement for static cells that however occupy much less space (and thus costs less fees for storage and sending).
25
+
## Structure of Library Cells
23
26
24
-
Note, that it is possible to make library cell that is reference to library cell that is reference to library cell ... and so on. For such case `.begin_parse()` will raise exception. Such library however can be unwrapped step-wise via `XLOAD` opcode.
27
+
Library cell is [exotic cell](/develop/data-formats/exotic-cells) that contains a reference to some other static cell. In particular it contains 256 bit of hash of referenced cell.
25
28
26
-
Another important peculiarities of Library Cell is that since it contains hash of referenced cell it is ultimatively reference to some satic data. You can not change data to which this library cell is referenced.
29
+
For TVM, library cells works as follows: whenever TVM receives a command to open a cell to a slice (TVM Instruction: `CTOS`, funC method: `.begin_parse()`), it searches cell with the corresponding hash from library cell in the Masterchain library context. If found it, it opens referenced cell and returns its slice.
27
30
31
+
Opening library cell costs the same as opening ordinar cell, so it can be used as transparent replacement for static cells that however occupy much less space (and thus costs less fees for storage and sending).
32
+
33
+
Note that it is possible to create a library cell that references another library cell, which in turn references another, and so on. For such case `.begin_parse()` will raise exception. Such library however can be unwrapped step-wise with `XLOAD` opcode.
34
+
35
+
Another important peculiarities of Library Cell is that since it contains hash of referenced cell it is ultimatively reference to some satic data. You can not change data to which this library cell is referenced.
28
36
29
-
To be found in the Masterchain library context and thus referenced by some Library Cell, source Cell need to be published in masterchain. That means that some smartcontract that exist in masterchain need to add this cell as library to it's state with `public=true` flag. That can be done via `SETLIBCODE` opcode.
37
+
To be found in the Masterchain library context and thus referenced by a Library Cell, a source Cell needs to be published in the Masterchain. This means that a smart contract existing in the Masterchain needs to add this cell to its state with the `public=true` flag. This can be accomplished using the `SETLIBCODE` opcode.
30
38
31
39
## Using in Smart Contracts
32
40
33
41
Since library cell behaves the same way as ordinary cell it referenced to in all contexts except fee calculation you can just use it instead of any cell with static data. For instance, you can store jetton-wallet code as library cell (so 1 cell and 256+8 bits, instead of usually ~20 cells and 6000 bits) which will result is order magnitude less storage and forward fees. In particular, forward fees for `internal_transfer` message that contains `init_code` will be decreased from 0.011 to 0.003 TON.
34
42
35
-
### Store Data in the library cell
43
+
### Store Data in the Library Cell
36
44
Lets consider example of storing jetton-wallet code as library cell to decrease fees. First we need to compile jetton-wallet to ordinary cell that contains it's code.
37
45
38
46
Than you need to create library cell with reference to ordinary cell. Library cell contains 8-bit tag of library `0x02` followed by 256-bit of referenced cell hash.
39
47
40
-
So basically you need to put tag and hash to the builder and then "close builder as exotic cell".
48
+
### Using in Fift
49
+
Basically you need to put tag and hash to the builder and then "close builder as exotic cell".
41
50
42
51
It can be done in Fift-asm construction like [this](https://github.com/ton-blockchain/multisig-contract-v2/blob/master/contracts/auto/order_code.func), example of compilation some contract directly to library cell [here](https://github.com/ton-blockchain/multisig-contract-v2/blob/master/wrappers/Order.compile.ts).
43
52
@@ -49,8 +58,8 @@ It can be done in Fift-asm construction like [this](https://github.com/ton-block
49
58
50
59
cell order_code() asm "<b 2 8 u, 0x6305a8061c856c2ccf05dcb0df5815c71475870567cab5f049e340bcf59251f3 256 u, b>spec PUSHREF";
51
60
```
52
-
53
-
Alternatively, you can form Library Cell entirely on ts-level in Blueprint via `@ton/ton`like [this](https://github.com/ton-blockchain/stablecoin-contract/blob/de08b905214eb253d27009db6a124fd1feadbf72/sandbox_tests/JettonWallet.spec.ts#L104C1-L105C90).
61
+
### Using in @ton/ton
62
+
Alternatively, you can form Library Cell entirely on ts-level in Blueprint with the `@ton/ton`library:
54
63
55
64
```ts
56
65
import { Cell, beginCell } from'@ton/core';
@@ -59,14 +68,14 @@ let lib_prep = beginCell().storeUint(2,8).storeBuffer(jwallet_code_raw.hash()).e
### Publish ordinary cell in masterchain library context
63
74
Practical example is available [here](https://github.com/ton-blockchain/multisig-contract-v2/blob/master/contracts/helper/librarian.func). The core of this contract is `set_lib_code(lib_to_publish, 2);` - it accepts as input ordinary cell that need to be published and flag=2 (means that everybody can use it).
64
75
65
76
Note, that contract that publish cell pays for it's storage and storage in masterchain 1000x higher than in basechain. So library cell usage is only efficient for contracts used by thousands users.
66
77
67
-
### Testing in Blueprint
68
-
69
-
78
+
### Testing in the Blueprint
70
79
71
80
To test how contract that use Library Cells work in blueprint you need to manually add referenced cells to library context of blueprint emulator. It can be done this way:
72
81
1) you need to create library context dictionary (Hashmap) `uint256->Cell` where `uint256` is hash of the corresponding Cell.
@@ -102,3 +111,9 @@ as well as list of libraries for specific masterchain block:
0 commit comments