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 successfully built contract, Acton generates a JSON artifact in the output directory (default: build/) containing the base64-encoded code and its hash. When ABI is available, Acton writes compiler ABI JSON files to the ABI output directory (default: build/abi/). Precompiled .boc contracts get ABI only when they set types.

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

# Show compiled code and hash information
acton build Counter --info

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 [contracts.ID] in Acton.toml is used:

• As a contract entrypoint, referencing a Tolk file with onInternalMessage()
• 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

Generated wrapper filenames are based on the source file stem normalized to PascalCase. With the conventional src = "contracts/Counter.tolk", that produces wrappers/Counter.gen.tolk and wrappers-ts/Counter.gen.ts.

Contract IDs 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 = "Child", kind = "library_ref", function = "getChildCode", path = "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. The -, ., and spaces are replaced with _
2. If the first character is not alphabetic, they are prefixed with contract_
3. The result is converted to camelCase
4. CompiledCode suffix is appended.

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

It is possible to use precompiled .boc files instead of .tolk sources:

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

When using .boc files:

• Contract code is not compiled
• The BoC code is loaded directly without running the Tolk compiler on that code
• If types is set, Acton compiles that Tolk file as an interface-only source to emit ABI and generate wrappers
• Other contracts can still reference this contract in their depends
• depends on the BoC contract itself has no effect on its code because the BoC is already compiled
• acton build always writes the regular JSON artifact for a valid BoC contract. If types is configured, it also writes ABI JSON to the ABI output directory. output = "path/to/file.boc" can still write the normalized BoC output.
• --output-fift only applies to compiled .tolk contracts. BoC contracts are already compiled, so Acton does not produce Fift for them.

This is useful for referencing third-party contracts.

For the user-facing workflow, including interface files and wrapper generation, see Precompiled BoC contracts.

This build mode is separate from TON network precompiled contracts configured through Param 45. During local emulation and tests, Acton honors Param 45 entries by contract code hash. When the executed account code hash matches a PrecompiledContractsConfig entry, GETPRECOMPILEDGAS observes the configured gas value and the resulting transaction reports that fixed gas usage with vm_steps = 0, matching the network transaction shape.

Acton still executes the contract code through TVM fallback in this case; native C++ precompiled implementations are not used by the local emulator. This keeps storage updates, actions, exit codes, and other contract behavior tied to the actual contract code while using the network-defined fixed gas accounting. Writing an empty Param 45 dictionary, or omitting the matching code hash, makes the contract execute as a regular TVM contract.

See PrecompiledContractsConfig for the standard library helpers used to inspect or override Param 45 in tests.

Path mappings

Define additional 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, and wrappers, while --app scaffolds use contracts/src, contracts/tests, and contracts/wrappers. Acton does not recreate these folders 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:

brew install graphviz

sudo apt-get install graphviz

The generated DOT contains:

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