acton library
Reference manual for the acton library command
Synopsis
acton library [options] command
Description
Publish, fetch, inspect, and top up on-chain TON libraries.
Library metadata can also be stored locally in libraries.toml or globally in
global.libraries.toml for later inspection and maintenance.
Lifecycle
A typical library workflow is:
publisha contract or code cell- save metadata locally or globally for later lookup
- inspect runtime state with
info fetchthe code again for inspection or backuptopupthe library account when more storage time is needed
Subcommands
acton library publish
Publish a contract or arbitrary code as a library.
Synopsis
acton library publish [options] [contract-name]
Options
Contract name to publish.
Use --code to publish arbitrary code instead of compiling a project contract.
Base64 or hex code to publish instead of compiling a contract.
Requested publication duration such as 100d or 1y.
Wallet to use for the publication transaction.
Network to use.
testnet.
Explicit TON amount to send.
Overrides duration-based estimation.
Skip confirmation prompts.
Save library metadata to local libraries.toml.
Save library metadata to global global.libraries.toml.
acton library fetch
Fetch library code from the blockchain by hash.
Synopsis
acton library fetch [options] hash
Options
Library code hash.
Disassemble the fetched code and print TASM.
Write fetched output to a file.
If --disasm is used, the output is text. Otherwise Acton writes binary BoC
for .boc paths and base64 text for other paths.
Network to use.
testnet.
Emit JSON output for raw library fetches.
If --disasm is also passed, Acton prints disassembly text instead.
acton library info
Show information about a deployed library.
Synopsis
acton library info [options] [name]
Options
Library name to inspect.
Acton can prompt from the available library metadata.
The output includes publication time, last top-up time, current balance, and estimated remaining storage runway.
acton library topup
Top up a library account for additional storage time.
Synopsis
acton library topup [options] [library-name]
Options
Library name to top up.
Requested additional storage duration such as 100d or 1y.
Explicit TON amount to send.
Overrides duration-based estimation.
Wallet to use for the top-up transaction.
Skip confirmation prompts.
After a successful top-up, Acton updates last_topup_timestamp in the stored
library metadata.
TonCenter API Keys
Built-in mainnet/testnet requests read TONCENTER_MAINNET_API_KEY or
TONCENTER_TESTNET_API_KEY, depending on the selected network.
For custom:<name>, Acton reads <NORMALIZED_NAME>_API_KEY. Custom network
names are uppercased and non-alphanumeric characters are replaced with _, so
custom:mock-remote becomes MOCK_REMOTE_API_KEY.
Acton loads .env automatically, so the simplest setup during project work is
usually to keep these keys there and use shell environment variables only for
one-off overrides or CI.
Display Options
Control when to use colored output.
auto, always, never
Project Options
Path to the Acton.toml file to use for this invocation.
Use this when running the command outside the project directory or when the manifest lives at a non-default location.
Path to the project root to use for configuration discovery and relative defaults.
This conflicts with --manifest-path.
Resolution Rules
- library metadata is merged from
global.libraries.tomlfirst and then locallibraries.toml - when both files define the same library name, the local entry wins on lookup
- when saving new metadata into a file that already contains the requested
library ID, Acton appends
-1,-2, and so on to keep the existing record - if neither
--localnor--globalis passed topublish, Acton prompts for the destination file
Amount Estimation
For publish and topup, --duration is used to estimate the required TON
amount from the library size and storage duration.
If --amount is passed, it overrides that estimate completely.
Metadata Files
Saved library metadata typically includes:
- name
- hash
- code
- account
- duration
- network
- publication timestamp
- last top-up timestamp
- code size in bits and cells
Fetch Output
- without
--output, fetched code is printed to stdout - with
--output path.boc, Acton writes binary BoC - with
--outputto any other path, Acton writes base64 text - with
--disasm, stdout and file output are always disassembly text - with
--json, Acton prints JSON to stdout and does not also write--output - if both
--jsonand--disasmare passed, disassembly text takes precedence over JSON on successful runs
Exit Status
0: The selected library subcommand completed successfully.1: Contract or wallet resolution failed, chain access failed, metadata could not be written, or publish/top-up transaction preparation or submission failed.
Examples
-
Publish a contract as a library:
acton library publish Math --duration 365d --wallet deployer -
Publish arbitrary code:
acton library publish --code "te6cckEBAQEAAgAAAEysuc0=" --duration 100d -
Fetch and disassemble a library:
acton library fetch <HASH> --disasm -
Top up a library for one year:
acton library topup Math --duration 1y -
Fetch raw code into a BoC file:
acton library fetch <HASH> --output build/math-lib.boc
See Also
Last updated on