Build system

Two commands drive compilation:

• acton build runs the full project pipeline: it builds contracts registered in Acton.toml, compiles Tolk sources, loads precompiled BoC sources, resolves the dependency graph, and writes artifacts to be consumed by tests, wrappers, and scripts.
• acton compile targets a single .tolk file — useful for quick inspection of compiler output or producing standalone .boc and .fif files outside a project build.

Contract dependencies

Parent contracts often need child contract code at runtime — to deploy children or verify their code hash. The dependencies are declared in Acton.toml:

[contracts.JettonMinter]
src = "contracts/JettonMinter.tolk"
depends = ["JettonWallet"]

[contracts.JettonWallet]
src = "contracts/JettonWallet.tolk"
depends = []

See how to declare contract dependencies in the project management guide.

No circular dependencies

Acton resolves the full dependency graph and compiles contracts in topological order. A circular dependency aborts the build before any contract is compiled:

Error: Circular dependency detected in contracts: A → B → A → C

Dependency-graph failures such as missing contracts or cycles happen before the main compile loop starts, so those failures do not leave behind partial build artifacts.

Best-effort builds

When built with acton build, each successful contract produces a JSON file with Base64-encoded contract code and the code hash in build/. When ABI is available, Acton also writes it to build/abi/. Dependency helper files are written to gen/ for contracts with declared dependencies.

Once dependency resolution succeeds, Acton builds eligible contracts, discarding those failed to compile and not aborting the build immediately. Same goes for artifact-writing failures. Further, artifacts produced from successful builds in the current run remain on disk.

Compilation of a parent contract may still fail if its dependency failed to build or its helper file in gen/ was never produced.

To limit the build set to a single contract and its transitive dependencies, provide its ID explicitly, e.g., by running acton build Counter.

Build caching

Acton uses a shared file-based cache under build/cache/. Compilation cache entries are keyed on the source file path, Tolk compiler version, optimization level, debug mode, Fift generation flag, and import mappings from Acton.toml.

A cache entry is valid only if the content hash of every imported source file matches the stored hash. This includes helper files generated in gen/, so changing a child contract's source also invalidates the cache for any parent that imports the generated helper.

The same cache directory is shared by acton build, acton compile, and acton test. Recent builds often speed up subsequent test runs.

Pinned fork runs also store fetched remote accounts in this directory under build/cache/<network>/<seqno>/<workchain>_<address-hash>.json. acton test and acton script reuse those files when the same fork network, block number, and account address are requested again.

Clear the cache to force a full rebuild:

acton build --clear-cache

See also

• Tolk wrappers

• Precompiled BoC contracts

• Build system reference

• acton build command reference

• acton compile command reference

• TypeScript wrappers

• acton wrapper command reference