Library references

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 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.

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”.

Limited availability

Since global TVM version 15, mainnet and testnet networks reject change-library actions from regular accounts in every workchain, including the masterchain (-1) and basechain (0). Only special masterchain accounts, such as the ones hosting elector and config smart contracts, can add or remove public libraries.

However, operations such as obtaining library metadata or performing a top-up are allowed for existing libraries.

Low-level details

Library cells 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 maps 256-bit representation hashes to their cells. When TVM accesses a library reference, it looks up the hash and transparently replaces the reference with the matching cell.

At global TVM version 15 or later, a smart contract's library environment contains only the global public libraries recorded in the masterchain state. TVM does not add libraries from the account's StateInit.library dictionary or the inbound message's StateInit.library dictionary. A library reference resolves only when its hash exists in the global public library environment.

Public library storage

Public libraries are registered through special masterchain accounts and stored in the account's library field.

_ 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;

The public field remains part of the serialized SimpleLib structure:

public = 1 identifies a public library. Only a special masterchain account can add or remove this entry.
public = 0 identifies a private library. The action phase rejects attempts to add one, and TVM does not include existing private entries in the library environment.

A public library remains available while at least one active publisher account keeps it registered. Maintaining enough Gram on publisher accounts prevents storage debt from freezing them.