Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
While cells are deduplicated by hash within each data store on TON, there might be situations where cells with the same hash are required in several stores. For example, if there is a popular contract with a lot of instances, and there's no need to duplicate and store separately part of its code for every instance.
This is where libraries are needed: they store a single cell that is available to all the contracts. Library reference cells store a hash of such a library, and tell TVM to look up the content of such a library cell. This might reduce the size of serialized data and enable efficient storage of incrementally updated data.
The library reference has level `0`, so it does not contain any higher hashes.
Each library cell is serialized as follows:
* The 1-byte tag that always equals `0x02`.
* The 256-bit [representation hash](/foundations/serialization/cells) of the library cell being referred to.
## 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.
The library allows extending the deduplication mechanism on-chain, enabling the incorporation of the same efficiency into custom smart contracts.
### 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:
1. The global library environment for the workchain in question is taken from the current state of the Masterchain.
2. 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.
3. 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 the `library` field in the account.
```tlb theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
_ fixed_prefix_length:(Maybe (## 5)) special:(Maybe TickTock)
code:(Maybe ^Cell) data:(Maybe ^Cell)
library:(HashmapE 256 SimpleLib) = StateInitWithLibs;
simple_lib$_ public:Bool root:^Cell = SimpleLib;
```
One can see the `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.
### Other articles
Library cells are mainly used to minimize storage costs for accounts with identical code. Read more about this [pattern](/contract-dev/using-on-chain-libraries).