Introduction
One of the native features of how TON stores data in cells is deduplication: duplicate cells are stored only once in storage, messages, blocks, transactions, and other elements. This significantly reduces the size of serialized data and enables efficient storage of incrementally updated data. Library allows to extend deduplication mechanism on-chain, enabling the incorporation of the same efficiency into custom smart contracts.You can think of a library cell as a const weak C++ pointer: a small cell that references a larger one, which may include many references. The referenced cell must exist and be registered publicly, i.e. “published”.
Low-level details
They always have level 0. They store a tag equal to 2 in the first 8 bits. Then 256 bits follow, which are the representation hash of the referenced cell. When a library cell is stored in account storage, the account pays storage for this cell equal to the cost of 1 cell and 256 + 8 bits.Hierarchical library cells
Library cells can reference other library cells. However, they are not automatically dereferenced by the CTOS instruction (begin_parse
in FunC). Attempting to do so results in exit code 9. Use XLOAD
or XCTOS to dereference explicitly.
Creating libraries that reference a cell whose tree contains other library cells is fine.
Smart-contract library environment
When a contract tries to load a library cell, the library is looked up in its library environment. The library environment of a smart contract is a hashmap mapping 256-bit cell (representation) hashes to the corresponding cells themselves. When an external cell reference is accessed during the execution of a smart contract, the referenced cell is looked up in the library environment and the external cell reference is transparently replaced by the cell found. The library environment for an invocation of a smart contract is computed as follows:- The global library environment for the workchain in question is taken from the current state of the Masterchain.
- Next, it is augmented by the local library environment of the smart contract, stored in the library field of the smart contract’s state. Only 256-bit keys equal to the hashes of the corresponding value cells are taken into account. If a key is present in both the global and local library environments, the local environment takes precedence while merging the two library environments.
- Finally, the message library stored in the library field of the init field of the inbound message is similarly taken into account. Note, however, that if the account is frozen or uninitialized, the library field of the message is part of the suggested state of the account and is used instead of the local library environment in the previous step. The message library has lower precedence than both the local and the global library environments.
Hosting a library cell
Libraries are hosted in the states of accounts. More specifically, they reside in thelibrary
field in the account.
public
flag in SimpleLib.
This flag allows making a library cell private (accessible only from the account hosting it), even if the account hosting it resides in the Masterchain.
Also, if the account hosting the library becomes frozen, the library becomes inaccessible. So it is crucial to keep in mind that storage costs in the Masterchain are much higher than in the Basechain and to carefully control the balance of the account that hosts the library.