Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
Before using on-chain libraries, read about [library cells](/foundations/serialization/library). That page explains the cell format that on-chain libraries use.
## When to use
Use library cells when multiple contracts share the same code and forwarding or storage costs need to be reduced, *resulting in fee savings*.
For example, in [jettons](/standard/tokens/jettons/overview), the [`StateInit`](/foundations/messages/deploy) must be forwarded with each transfer, which increases forwarding fees. Moving the code into a library cell reduces that overhead.
However, a library must be hosted in the masterchain, where storage is more expensive than in the basechain. If fewer than about 1,000 contracts share the same code, storing a copy in the basechain can be cheaper.
The exact ratio depends on blockchain [config parameter 18](/foundations/config#param-18-storage-prices). Compare storage and forwarding costs before choosing this approach.
### Common use cases
Everything in TON is stored in cells, including the account code. A common use case for libraries is shared code across multiple contracts. When a library cell is part of an account's `code`, the runtime dereferences it on first access. This makes it possible to replace part of the contract code, or even the entire code, with a library cell.
Replacing the entire code with a library cell is used in TON smart contracts. Examples include:
1. USDT and other jetton wallet contracts;
2. Multisig v2 order contracts;
3. NFT item contracts in popular collections.
### Check for library usage
Check whether a contract uses a library as its code by inspecting its `code` cell in an [explorer](/ecosystem/explorers/overview).
```txt title="Partial explorer snippet of a USDT jetton wallet account" 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"]}}
...
code:(just
value:(raw@^Cell
x{}
SPECIAL x{028F452D7A4DFD74066B682365177259ED05734435BE76B5FD4BD5D8AF2B7C3D68}
))
...
```
The exact representation in the [TON Explorer](https://explorer.toncoin.org/) is not important. The key point is that the contract code contains a single `SPECIAL` cell, which indicates an exotic cell. The first byte equals `2`, which marks a library cell. The remaining bytes contain the hash of the referenced cell.
In this form, the entire contract code consists of the 8-bit tag `2` and the 256-bit representation hash of the referenced cell.
If only part of the code should live in a library cell, move the shared function into a library instead. This approach is used when multiple contracts reuse the same function. The build process for this setup may require custom tooling.
## Use `@ton/core`
Construct a library cell in TypeScript with the `@ton/core` library. The following example shows the pattern in a Blueprint project:
```ts title="TypeScript" 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"]}}
import { Cell, beginCell } from '@ton/core';
const libPrep = beginCell().storeUint(2, 8).storeBuffer(jwalletCodeRaw.hash()).endCell();
const jwalletCode = new Cell({ exotic: true, bits: libPrep.bits, refs: libPrep.refs });
```
Reference implementation: [`JettonWallet.spec.ts`](https://github.com/ton-blockchain/stablecoin-contract/blob/de08b905214eb253d27009db6a124fd1feadbf72/sandbox_tests/JettonWallet.spec.ts#L104C1-L105C90).
## Publish an ordinary cell in the masterchain library context
The following Tolk example is based on the librarian contract from the [multisig v2 repository](https://github.com/ton-blockchain/multisig-contract-v2/blob/master/contracts/helper/librarian.func).
```tolk title="Tolk" expandable 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"]}}
import "@stdlib/gas-payments"
const DEFAULT_DURATION = 3600 * 24 * 365 * 10 // 10 years, can top-up any time
const MAX_LIBRARY_CELLS = 1000 // Network config limit for library cells
const PUBLIC_LIBRARY_MODE = 2 // Public library mode for masterchain contracts
// https://docs.ton.org/tvm/instructions#fb06-setlibcode
fun setLibCode(code: cell, mode: int): void
asm "SETLIBCODE"
fun onInternalMessage(in: InMessage) {
val senderAddress = in.senderAddress;
val libToPublish = contract.getData();
val initialGas = getGasConsumedAtTheMoment();
val (orderCells, orderBits, _) = libToPublish.calculateSizeStrict(MAX_LIBRARY_CELLS);
val sizeCountingGas = getGasConsumedAtTheMoment() - initialGas;
val toReserve =
calculateGasFeeWithoutFlatPrice(-1, sizeCountingGas) +
calculateStorageFee(-1, DEFAULT_DURATION, orderBits, orderCells);
reserveToncoinsOnBalance(toReserve, RESERVE_MODE_BOUNCE_ON_ACTION_FAIL);
val reply = createMessage({
bounce: BounceMode.NoBounce,
dest: senderAddress,
value: 0
});
reply.send(SEND_MODE_CARRY_ALL_BALANCE);
setLibCode(libToPublish, PUBLIC_LIBRARY_MODE);
contract.setCodePostponed(createEmptyCell());
contract.setData(createEmptyCell());
}
```
This contract requires enough TON for at least 10 years of storage. That prevents the library from freezing shortly after publication and becoming inaccessible.
The key line is `setLibCode(libToPublish, PUBLIC_LIBRARY_MODE);`. This call publishes an ordinary cell with the flag set to `2`, which makes the library public.
## Test libraries with Acton
Refer to the [on-chain libraries guide](https://ton-blockchain.github.io/acton/docs/libraries) in Acton documentation.
## Test libraries with Blueprint
When testing smart contracts locally, there are two ways to register libraries in the blockchain environment: automatically and manually.
### Automatic library deployment
Enable automatic library detection by passing the `autoDeployLibs` flag when creating the blockchain:
```ts title="TypeScript" 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"]}}
const blockchain = await Blockchain.create({ autoDeployLibs: true });
```
For contracts deployed in the masterchain, publish the library with the librarian example above.
This lets the contract install and register the library at runtime, while the environment tracks and uses it automatically.
### Manual library deployment
If `autoDeployLibs` is not enabled, register libraries manually:
```ts title="TypeScript" 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"]}}
const blockchain = await Blockchain.create();
const code = await compile('Contract');
// Create a dictionary of library hash → library cell
const libsDict = Dictionary.empty(Dictionary.Keys.Buffer(32), Dictionary.Values.Cell());
libsDict.set(code.hash(), code);
// Manually assign the libraries
blockchain.libs = beginCell().storeDictDirect(libsDict).endCell();
```
This approach gives full control, but it requires explicit management of the libraries available during testing.
Reference implementation: [`JettonWallet.spec.ts`](https://github.com/ton-blockchain/stablecoin-contract/blob/de08b905214eb253d27009db6a124fd1feadbf72/sandbox_tests/JettonWallet.spec.ts#L100C9-L103C32).
## Get methods for library-backed contracts
When working with a jetton wallet whose code is stored in a library cell, check its balance by executing a get method.
When methods run through the [HTTP API](/ecosystem/api/overview) or [liteserver](/ecosystem/nodes/overview), the library cell is resolved automatically and the method runs against the resolved code.
For local execution, pull the account state and resolve every library reference cell first. In most cases, the entire code cell is itself a library reference.
To resolve a library, call the [`/getLibraries` method](/ecosystem/api/toncenter/v2/configuration/get-libraries).
### Retrieve a library cell with Acton
To inspect an existing library or read its code, use `acton library fetch`:
```bash 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"]}}
acton library fetch
```
See the [on-chain libraries guide](https://ton-blockchain.github.io/acton/docs/libraries) in Acton documentation for more.
### Retrieve a library cell with liteserver
To retrieve library cells from liteserver, use the [`liteServer.getLibraries`](https://github.com/ton-blockchain/ton/blob/4cfe1d1a96acf956e28e2bbc696a143489e23631/tl/generate/scheme/lite_api.tl#L96) method.
```ts title="TypeScript" expandable 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"]}}
import { LiteClient, LiteRoundRobinEngine, LiteSingleEngine } from "ton-lite-client";
import { Cell } from "@ton/core";
import { z } from "zod";
function intToIP(int: number): string {
const buf = Buffer.alloc(4);
buf.writeUInt32BE(int >>> 0, 0);
return Array.from(buf).join(".");
}
const Server = z.object({
ip: z.number(),
port: z.number(),
id: z.object({ key: z.string() }),
});
const Response = z.object({
liteservers: z.array(Server),
});
// testnet https://ton.org/testnet-global.config.json
// mainnet https://ton.org/global.config.json
const configEndpoint = "https://ton.org/global.config.json";
async function getServers() {
const data = Response.parse(await (await fetch(configEndpoint)).json());
return data.liteservers.map((server) => {
return new LiteSingleEngine({
host: `tcp://${intToIP(server.ip)}:${server.port}`,
publicKey: Buffer.from(server.id.key, 'base64'),
});
});
}
async function getLibraryByHash(hash: Buffer) {
const engine = new LiteRoundRobinEngine(await getServers());
const client = new LiteClient({ engine });
const libs = await client.getLibraries([hash]);
const lib = libs.result[0];
if (!lib || libs.result.length !== 1) {
throw new Error("Library not found");
}
const roots = Cell.fromBoc(lib.data);
const root = roots[0];
if (!root || roots.length !== 1) {
throw new Error("Malformed BoC for a library");
}
return root.toBoc().toString("hex");
}
async function main() {
const hash = Buffer.from("8F452D7A4DFD74066B682365177259ED05734435BE76B5FD4BD5D8AF2B7C3D68", "hex");
const code = await getLibraryByHash(hash);
console.log(code);
}
void main();
```