Reference

This page provides a complete reference for all configuration options available in Acton's build system.

Path Resolution Rules

Acton uses two different path-resolution models:

• Relative paths from Acton.toml are resolved from project root.
• Relative CLI path flags stay relative to the current working directory unless absolute.
• --manifest-path only chooses which manifest to load. It does not rebase unrelated CLI path flags to the manifest directory.

Examples:

• [build].out-dir = "artifacts" resolves to <project-root>/artifacts.
• acton build --out-dir artifacts resolves to <cwd>/artifacts.
• [wrappers.tolk].output-dir = "wrappers" is project-root-relative, while acton wrapper Counter --output-dir wrappers is cwd-relative.

acton build

Compile all contracts defined in Acton.toml or a specific contract with its dependencies.

For each compiled contract, Acton generates a JSON artifact in the output directory (default: build/) containing the compiled base64-encoded code and its hash. For .tolk contracts, Acton writes compiler ABI JSON files to the ABI output directory (default: build/abi/).

acton build [OPTIONS] [CONTRACT]

Arguments

Options

Examples

# Build all contracts
acton build

# Build only the Counter contract and its dependencies
acton build Counter

# Clear cache and rebuild everything
acton build --clear-cache

# Build with custom graph path
acton build --graph diagrams/dependencies.dot

# Build with custom output directory for JSON artifacts
acton build --out-dir artifacts/

# Build with custom output directory for generated dependency files
acton build --gen-dir generated/

# Build with custom output directory for ABI JSON files
acton build --output-abi build/abi

# Build and save compiled Fift files for each contract
acton build --output-fift build/fift

Acton.toml Configuration

Build Section

Use [build] to configure default outputs for acton build:

[build]
out-dir = "build"
gen-dir = "gen"
output-abi = "build/abi"
output-fift = "build/fift"

out-dir controls where JSON artifacts are written (<out-dir>/<contract>.json). gen-dir controls where dependency code is generated by default (<gen-dir>/<dependency>.code.tolk). output-abi controls where compiler ABI JSON files are written (<output-abi>/<contract>.json). When output-fift is set, Acton writes one file per compiled .tolk contract: <output-fift>/<contract-name>.fif. Contracts with src = "*.boc" are not recompiled, so no .fif file is produced for them.

CLI flags have priority over config values. Example:

acton build --out-dir artifacts
acton build --gen-dir artifacts/gen
acton build --output-abi artifacts/abi
acton build --output-fift artifacts/fift

Config values in [build] are project-root-relative. CLI paths such as --out-dir, --gen-dir, --output-abi, --output-fift, and --graph remain cwd-relative unless absolute.

Wrappers Section

Use [wrappers] to configure default output locations for acton wrapper:

[wrappers.tolk]
output-dir = "wrappers"
generate-test = true
test-output-dir = "tests"

[wrappers.typescript]
output-dir = "app/src/wrappers-ts"

Available fields:

Override rules:

• Tolk wrapper path: --output -> --output-dir -> [wrappers.tolk].output-dir -> @wrappers mapping -> wrapper command built-in default.
• TypeScript wrapper path: --output -> --output-dir -> [wrappers.typescript].output-dir -> wrapper command built-in default.
• Test stub path: --test-output -> --test-output-dir -> [wrappers.tolk].test-output-dir -> wrapper command built-in default.
• [wrappers.tolk].generate-test only affects non-TypeScript runs. acton wrapper --ts still rejects test-stub options.

Configured wrapper paths are project-root-relative. CLI paths such as --output, --output-dir, --test-output, and --test-output-dir remain cwd-relative unless absolute.

Contracts Section

Contracts are defined using [contracts.*] sections where * is the contract name.

[contracts.MyContract]
display-name = "MyContract"
src = "contracts/MyContract.tolk"
output = "build/MyContract.boc"
depends = []

Contract Fields

Contract Names

The contract name ([contracts.NAME] in Acton.toml, e.g., Counter) is used:

• As a contract entrypoint contracts/Counter.tolk (with onInternalMessage, get methods, etc.)
• As a filename for generated wrappers (e.g., wrappers/Counter.gen.tolk, wrappers-ts/Counter.gen.ts)
• As the dependency name when referencing this contract
• To generate the output file name in the dependency output directory (default: gen/, e.g., Counter → gen/Counter.code.tolk)
• To generate the function name (e.g., Counter → counterCompiledCode())
• In console messages and web UI, unless overridden by optional display-name in Acton.toml

Names should use PascalCase (e.g., JettonWallet, NftCollection).

Dependencies Configuration

Dependencies can be specified in two formats:

Simple Format

depends = ["ChildContract", "AnotherContract"]

Uses default settings:

• kind = "embed_code"
• Generated file: {gen-dir}/{contract-name}.code.tolk (gen-dir defaults to gen)
• Generated function: auto-derived from the dependency key using the normalization rules below

Detailed Format

depends = [
  { name = "ChildContract", kind = "library_ref", function = "getChildCode", path = "contracts/gen/child.code.tolk" }
]

Dependency Helper Generation Rules

Acton generates one helper file per direct dependency of the parent contract. Those helper paths and function names are derived from the dependency name (the [contracts.<name>] key), not from display-name.

Helper file placement uses this precedence:

1. depends[].path
2. acton build --gen-dir
3. [build].gen-dir
4. <project-root>/gen

Path resolution follows the normal config-vs-CLI rules:

• depends[].path and [build].gen-dir are project-root-relative unless absolute
• --gen-dir is cwd-relative unless absolute
• if depends[].path is set, it fully replaces the default helper location

Default helper filenames use the raw dependency key:

• Wallet -> gen/Wallet.code.tolk
• child.lib -> gen/child.lib.code.tolk
• 123contract -> gen/123contract.code.tolk

Default helper function names are normalized separately:

1. Replace -, ., and spaces with _
2. If the first character is not alphabetic, prefix contract_
3. Convert the result to lowerCamelCase
4. Append CompiledCode

Examples:

• Wallet -> walletCompiledCode()
• child.lib -> childLibCompiledCode()
• 123contract -> contract123contractCompiledCode()

Custom function overrides only the function name. Custom path overrides only the output file location.

Dependency Kinds

embed_code (default)

Embeds the full compiled contract code directly into the parent contract.

depends = ["Wallet"]
# or
depends = [{ name = "Wallet", kind = "embed_code" }]

Generated assembly:

@pure
fun walletCompiledCode(): cell asm """
    "<base64_boc_data>" base64>B B>boc PUSHREF
"""

library_ref

Generates a library reference instead of embedding full code. The library must be deployed separately.

depends = [{ name = "Wallet", kind = "library_ref" }]

Generated assembly:

@pure
fun walletCompiledCode(): cell asm """
    "<base64_boc_data>" base64>B B>boc hashu <b 2 8 u, swap 256 u, b>spec PUSHREF
"""

Using Precompiled Contracts

You can use precompiled .boc files instead of .tolk sources:

[contracts.Precompiled]
display-name = "PrecompiledContract"
src = "contracts/Precompiled.boc"
depends = []

When using .boc files:

• No compilation is performed
• The BoC is loaded and cached directly
• Dependencies can still reference this contract
• Useful for third-party contracts or cross-platform builds

Path Mappings

You can define path aliases for the Tolk compiler in the [import-mappings] section. These are useful for importing library code without using complex relative paths.

[import-mappings]
core = "./libs/core"
utils = "./libs/utils"

In Tolk code:

import "@core/math.tolk"

Built-in project mappings commonly used in Acton projects:

These defaults are usually written into Acton.toml by acton new and acton init. Standard scaffolds use contracts / tests / wrappers, while --app scaffolds use contracts/src / contracts/tests / contracts/wrappers. If you remove them manually, Acton does not recreate them during normal compilation.

Mappings follow these rules:

1. Normalization: Any mapping key missing the @ prefix will have it added automatically.
2. Resolution: Mappings are resolved relative to project root for the current invocation.
3. Exact Match: When importing, the first part of the path (before the first slash) is used to look up the mapping. For example, import "@core/math.tolk" will look for a mapping named @core.

Dependency Graph Visualization

Generate a DOT representation of contract dependencies:

acton build --graph deps.dot

To render DOT into SVG manually (optional), use Graphviz:

# macOS
brew install graphviz

# Ubuntu/Debian
sudo apt-get install graphviz

# Windows
# Download from https://graphviz.org/download/

The generated DOT contains:

• Contract boxes labeled with contract names
• Arrows indicating dependencies
• Edge labels showing dependency kind (embed code or library ref)