On-chain libraries

On-chain libraries are a powerful feature of the TON blockchain that allows you to store code once and reuse it across multiple contracts, significantly reducing storage costs.

Publishing a Library

Acton provides a convenient command to publish any code as a library to the Masterchain.

Step 1: Create a contract

First, create a simple contract that you want to publish as a library. For example, let's create a Math.tolk file:

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

Make sure to register it in your Acton.toml:

[contracts.Math]
display-name = "Math Library"
src = "contracts/Math.tolk"

Step 2: Publish the library

Use the acton library publish command to deploy your library. You can specify the contract name defined in Acton.toml:

acton library publish Math

The CLI will guide you through the process:

1. Compiling: Acton will compile your contract to get the code cell.
2. Duration: You'll be asked how long you want to store the library (e.g., 365d for 1 year).
3. Cost Estimation: Acton will automatically calculate the required storage fee based on the code size and duration.
4. Wallet: Select a wallet to pay for the deployment.
5. Payment: Confirm the transaction amount. The CLI suggests a safe amount (120% of storage fee + gas).

Upon success, you will see the Library Hash. This hash is what you'll use to reference the library in other contracts.

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

Advanced Options

You can also publish arbitrary code using the --code flag or specify options non-interactively:

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

# Non-interactive mode
acton library publish Math --duration 100d --wallet my-wallet --net mainnet

Monitoring Library Status

Once a library is published, it's important to monitor its balance to ensure it doesn't get frozen due to lack of TON for storage fees. Acton provides the info command for this:

acton library info Math

This command shows:

• Balance: Current balance of the library account.
• Last top-up: Timestamp used as the reference point for storage runway calculations.
• Remaining: Estimated storage runway based on current Masterchain storage prices and elapsed time since the last top-up.
• Hash and Account: The library's unique hash and its on-chain address.

If the estimated runway is exhausted, Acton prints an urgent warning to top up. This warning does not necessarily mean the account is already frozen, but it signals elevated freeze risk. For account state transitions (active/frozen/nonexist) and storage debt behavior, see TON docs: Address states.

Extending Library Lifetime

If a library is running low on funds, you can top it up using the topup command. You can either specify a duration or a direct TON 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, ensuring you send enough funds for the desired period. After a successful top-up, Acton updates the last_topup_timestamp field in library metadata.

Fetching a Library

If you want to inspect an existing library or get its code, use the acton library fetch command.

acton library fetch <LIBRARY_HASH>

Disassembling Library Code

To understand what a library does, you can disassemble its code immediately after fetching:

acton library fetch <LIBRARY_HASH> --disasm

This will print the TVM assembly (TASM) of the library code.

Saving to File

You can save the library code to a file for further analysis or usage:

# 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 provides handy functions for working with 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.