On-chain libraries

On-chain libraries let the TON blockchain store code once and reuse it across multiple contracts, which cuts storage use compared to duplicating the same code in every account.

Publishing a library

Acton provides acton library publish to publish code as a library on the masterchain.

Step 1: Create a contract

Create a minimal contract to publish as a library. For example:

fun add(a: int, b: int): int {
    return a + b;
}

Register it in Acton.toml:

[contracts.Math]
display-name = "Math on-chain library"
src = "contracts/Math.tolk"

Step 2: Publish the library

Run acton library publish with the contract name from Acton.toml:

acton library publish Math

The CLI walks through:

1. Compile: compile the contract to obtain the code cell.
2. Duration: prompt for storage duration, e.g., 365d for one year.
3. Cost estimate: compute the storage fee from code size and duration.
4. Wallet: select a wallet to pay deployment costs.
5. Payment: confirm the transaction amount suggested by the CLI: 120% of storage fee plus gas.

Upon success, the output includes the library hash used to reference the library from other contracts.

...
> Enter amount in GRAM (at least 0.1124 GRAM for 1 year):
> Send 0.1124 GRAM to publish library? Note that any extra GRAM will be refunded. Yes
✓ Transaction sent successfully
→ Library should be available soon at hash: b993c68...

Advanced options

Publish raw code with --code or run non-interactively:

# Publish raw BoC (hex or base64)
acton library publish --code "te6cckEBAQEAAgAAAEysuc0="

# Non-interactive mode
acton library publish Math --duration 100d --amount 0.2 --wallet my-wallet \
                                               --net mainnet --yes --local

Use --local or --global to skip the metadata storage prompt and save the library entry to libraries.toml or global.libraries.toml.

Monitoring library status

After publishing, monitor the library balance so storage fees do not drain and freeze the account. Use acton library info:

acton library info Math

This command prints:

• Balance: current balance of the library account.
• Last top-up: timestamp used as the reference for storage runway calculations.
• Remaining: estimated storage runway from current masterchain storage prices and time since the last top-up.
• Hash and account: the library hash and on-chain address.

When the estimated runway is exhausted, Acton prints a warning to top up. That warning does not guarantee the account is already frozen; it signals higher freeze risk.

For account state transitions (active, frozen, nonexist) and storage debt, see TON documentation on address states.

Extending library lifetime

When the balance is low, top up with acton library topup. Pass either a duration or a GRAM amount:

# Top up for another 2 years
acton library topup Math --duration 2y

# Top up with a specific amount
acton library topup Math --amount 5.0

The topup command uses the same cost estimation logic as publish. After a successful top-up, Acton updates the last_topup_timestamp field in library metadata.

Fetching a library

To inspect an existing library or read its code, use acton library fetch:

acton library fetch <LIBRARY_HASH>

Disassembling library code

Disassemble code right after fetch:

acton library fetch <LIBRARY_HASH> --disasm

This prints the TVM assembly (TASM) of the library code.

Saving to file

Save library code to a file for analysis or reuse:

# Save as base64
acton library fetch <LIBRARY_HASH> -o library.txt

# Save as binary BoC
acton library fetch <LIBRARY_HASH> -o library.boc

# Save as TASM
acton library fetch <LIBRARY_HASH> --disasm -o library.tasm

Working with libraries in tests and scripts

Acton exposes helpers for libraries:

• net.loadLibrary(...) loads a library by hash and returns its code as a cell, or null if the library is not found.
• testing.registerLibrary(...) registers a library in the current test blockchain so contracts can use it.
• testing.loadAndRegisterLibrary(...) fetches a library by hash and registers it in the current test blockchain, returning true on success and false otherwise.