Acton.toml

The Acton.toml file is the project manifest. It defines package metadata, contract definitions, test settings, and custom scripts.

The manifest conforms to the TOML 1.1 specification.

Project Root Resolution

Acton resolves project root for each CLI invocation using global flags:

• --project-root <PATH> sets project root explicitly (no search).
• Without --project-root, Acton searches from current directory up through parent directories for Acton.toml (up to git boundary) and uses its directory as project root.
• If no Acton.toml is found in that search range, project root falls back to current working directory.
• --manifest-path <PATH> selects Acton.toml for config loading only and does not change project root resolution.

This matters for all relative paths from config sections, e.g., [contracts].src, [build], [test], and [import-mappings], because they are resolved relative to project root for the current invocation.

Relative CLI path flags are a separate rule:

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

Examples:

• [build].out-dir = "artifacts" writes under <project-root>/artifacts.
• acton build --out-dir artifacts writes under <cwd>/artifacts.
• [wrappers.tolk].output-dir = "wrappers" resolves from project root, but acton wrapper Counter --output-dir wrappers resolves from the current working directory.

Root section

The top-level of Acton.toml contains the following sections:

• [package] — Project metadata.
• [toolchain] — Required Acton CLI version for this project.
• [contracts] — Definition of smart contracts in the project.
• [build] — Build command output settings.
• [wrappers] — Default output settings for acton wrapper.
• [fmt] — Tolk formatter settings for acton fmt.
• [localnet] — Default settings for acton localnet commands.
• [test] — Configuration for the test runner.
• [lint] — General linter configuration.
• [networks] — Custom network definitions.
• [scripts] — Custom shell commands or scripts.
• [import-mappings] — Path mappings for Tolk compiler imports.

[package]

Defines project metadata.

Example:

[package]
name = "my-awesome-contract"
description = "A project with Tolk smart contracts"
version = "0.1.0"
repository = "https://github.com/user/my-awesome-contract"
license = "MIT"

[toolchain]

Pins project-level tooling versions. Acton checks this section before running project commands and exits with an error when the installed CLI version does not match the configured version.

Example:

[toolchain]
acton = "1.1.0"

For preview-channel builds installed with acton up --trunk, set the pin to trunk instead of the numbered stable release:

[toolchain]
acton = "trunk"

acton up remains available when the configured version does not match, so the expected version can be installed from the same project directory.

[contracts]

This section is a map where each key is a contract name and the value is a contract configuration object.

For precompiled .boc contracts, types can point to a Tolk file that contains the contract header, message/storage types, and getters. Acton still loads code from src, but uses the types file to produce ABI and generate wrappers.

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

Do not put dependencies on the BoC contract itself: it is already compiled. Instead, put depends = ["Precompiled"] on the .tolk contract that needs the BoC code.

Contract dependencies

Dependencies can be specified in two ways:

1. Simple format: Just the name of another contract defined in Acton.toml.

   depends = ["AnotherContract"]

2. Detailed format: An object with additional settings.

   • name: Name of the contract to depend on.
   • kind: Dependency type. Either embed_code (default) or library_ref.
   • function: Custom name for the generated code function.
   • path: Custom output path for the generated code file.

Dependency helper naming uses the contract key from [contracts.<name>], not display-name. Relative dependency path values are resolved from the project root.

Example:

[contracts.MainContract]
display-name = "Main Contract"
src = "contracts/MainContract.tolk"
depends = [
    "ChildContract",
    { name = "LibraryContract", kind = "library_ref", function = "get_lib_code" }
]

[build]

Configures defaults for acton build.

Example:

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

acton build --out-dir <DIR>, acton build --gen-dir <DIR>, acton build --output-abi <DIR>, and acton build --output-fift <DIR> override these values for a single run. Config values here are project-root-relative. The CLI flags stay relative to the current working directory unless absolute paths are passed. Precompiled .boc contracts emit ABI only when their contract config sets types; they never emit Fift output.

[wrappers]

Configures default output locations for acton wrapper.

[wrappers.tolk]

[wrappers.typescript]

Example:

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

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

Override rules:

• For Tolk wrappers, --output has highest priority, then --output-dir, then [wrappers.tolk].output-dir, then the @wrappers mapping when present, then the wrapper command's built-in wrappers/ location.
• For TypeScript wrappers, --output has highest priority, then --output-dir, then [wrappers.typescript].output-dir, then the wrapper command's built-in default location.
• For Tolk test stubs, --test-output has highest priority, then --test-output-dir, then [wrappers.tolk].test-output-dir, then the wrapper command's built-in default test location.
• [wrappers.tolk].generate-test affects only non-TypeScript wrapper generation. acton wrapper --ts still cannot be combined with test-stub generation.

Configured wrapper paths are resolved from project root. CLI paths such as --output, --output-dir, --test-output, and --test-output-dir stay relative to the current working directory unless absolute.

For full CLI behavior, see acton wrapper.

[fmt]

Configures defaults for acton fmt.

Import groups are ordered as: @stdlib, @acton, @<other>, plain imports (import "foo"), ./, ../.

Example:

[fmt]
width = 100
ignore = ["contracts/generated/*.tolk"]
separate-import-groups = true

CLI flags still override config values for a single run (for example acton fmt --check).

[localnet]

Configures defaults for acton localnet.

Example:

[localnet]
port = 3010
fork-net = "testnet"
fork-block-number = 55000000
accounts = ["deployer", "user"]
rate-limit = 1
response-delay-ms = 300

acton localnet start --port <PORT>, --fork-net <NETWORK>, --fork-block-number <SEQNO>, --accounts <NAME[,NAME...]>, --rate-limit <RPS>, and --response-delay-ms <MS> override these values for a single run.

[test]

Configures the behavior of acton test.

TON Center API keys are configured through the process environment, not Acton.toml: use TONCENTER_TESTNET_API_KEY or TONCENTER_MAINNET_API_KEY when the built-in fork target needs authentication.

[test.coverage]

Configures default coverage behavior for acton test.

[test.fuzz]

Configures defaults for parameterized tests that explicitly opt into fuzzing with @test.fuzz, @test.fuzz(<runs>), or @test.fuzz({ ... }). Per-test annotations can override individual values with @test.fuzz({ runs: ..., max_test_rejects: ..., seed: ... }).

Mutation testing configuration

The [test.mutation] subsection configures default filters for acton test --mutate. Available rule IDs are documented in Mutation Rules.

• diff = "worktree" compares the current worktree with HEAD. Use it for uncommitted local changes. Untracked files are treated as fully changed.
• diff = "ref" compares against an explicit ref, tag, or commit and requires diff-ref.
• diff = "branch" compares the current branch against the merge-base with its upstream branch. Use diff-ref to override the base branch explicitly, or when the current branch has no upstream.
• mutation-levels keeps only selected rule levels. For example, ["critical", "major"] skips minor mutations.
• minimum-percent fails the run when the resulting mutation score drops below the threshold. Valid range: 0..=100.
• disable-rules excludes individual rule IDs after diff and level filters are applied.
• rules-file adds custom query-based rules from JSON. If a custom rule uses the same ID as a built-in rule, it overrides the built-in one. Run acton meta get-schema mutation-rules to print the JSON schema for that file format.

All filters compose, and the reported mutation score reflects only the mutants that remain after filtering. Compile errors are excluded from the score, and minimum-percent applies to that final mutation score.

Example:

[test]
reporter = ["console", "junit"]
fail-fast = true
fail-on-diff = true
gas-profile = "build/gas.cpuprofile"
gas-profile-format = "cpuprofile"
gas-profile-include-tests = false

[test.coverage]
enabled = true
format = "lcov"
include-wrappers = true
include-tests = true

[test.fuzz]
runs = 512
max-test-rejects = 4096
seed = 42

[test.mutation]
diff = "branch"
diff-ref = "origin/main"
mutation-levels = ["critical", "major"]
minimum-percent = 85
disable-rules = ["replace_plus_with_minus"]
rules-file = "mutation-rules.json"

CLI flags such as --mutation-diff, --mutation-diff-ref, --mutation-levels, --mutation-minimum-percent, --mutation-disable-rules, and --mutation-rules-file override these defaults for the current run.

The fail-on-diff is used together with baseline comparison mode (acton test --baseline-snapshot <FILE>). Gas profile options apply when gas-profile or --gas-profile <FILE> is set.

Combine them with ui = true or acton test --gas-profile <FILE> --ui to browse flamegraphs in Test UI. Set gas-profile-include-tests = true when .test.tolk unit-test get methods contain the hot path you want to inspect.

[lint]

Configures the Tolk linter (acton check).

Use [lint] for linter-wide settings and [lint.rules] for rule severities. For practical workflows and CI usage, see the linting page.

General settings

Example:

[lint]
exclude = ["contracts/generated/*.tolk", "contracts/legacy.tolk"]
max-warnings = 0 # fail on any warning
output-format = "sarif"

Excluded dependency files are still parsed for imports and types, but lint diagnostics for them are hidden. When passing an explicit target to acton check, either a contract name or a file path, that target is checked even if it matches exclude. Compiler errors are never hidden by exclude.

Project-wide discovery skips built-in directories such as .git, .github, .idea, .acton, node_modules, target, tolk-stdlib, .codex, and .claude, and non-.tolk contract entries such as .boc artifacts never become lint roots.

CLI flag acton check --output-format <FORMAT> overrides [lint].output-format for the current run. Use acton check --output-file <PATH> to write non-plain output into a file.

For one-off line-level suppressions in source code, use // check-disable-next-line ... comments. Suppressions use rule names, e.g., unused-variable, and do not affect compiler or parser diagnostics like C001: compiler-error.

See the project lint policy configuration for more.

Global configuration

Specify rules under [lint.rules] to apply them to all contracts in the project.

Example:

[lint.rules]
unused-variable = "deny"
mutable-variable-can-be-immutable = "warn"

Contract overrides

Override lint levels for specific contracts by creating a subsection named after the contract: the NAME in [contracts.NAME].

Example:

[contracts.Counter]
display-name = "My Counter"
src = "contracts/Counter.tolk"

[lint.rules]
unused-variable = "deny"

[lint.rules.Counter]
unused-variable = "allow" # Disable for the Counter contract only

[networks]

Defines network settings used by --net and --fork-net.

• mainnet and testnet are built in.
• localnet is a first-class network and is always available.
• Extra entries under [networks.<name>] are used as custom:<name>.

Example:

[networks.localnet]
explorer = "http://127.0.0.1:3006"

[networks.my-custom-net]
api = { v2 = "https://my-custom-net.com/api/v2", v3 = "https://my-custom-net.com/api/v3" }
explorer = "https://my-custom-net.com/explorer"

These networks work in commands such as:

• acton script --net localnet
• acton script --net custom:my-custom-net
• acton test --fork-net custom:my-custom-net

[scripts]

Allows defining custom scripts that can be executed via acton run <name>.

Example:

[scripts]
deploy = "acton script scripts/deploy.tolk"
check = "acton test --filter='.*_check'"

[import-mappings]

Allows defining path aliases for the Tolk compiler, similar to @stdlib. These mappings allow importing files using logical names instead of relative paths.

Example:

[import-mappings]
utils = "./libs/utils" # Equivalent to "@utils" and preferred
"@core" = "./libs/core"

With the above configuration, Tolk source files can import using those mappings:

import "@core/math"  // Resolves to ./libs/core/math.tolk
import "@utils/logic" // Resolves to ./libs/utils/logic.tolk

Built-in project mappings

Projects created with acton new, or initialized with acton init when Acton.toml did not exist yet, usually contain these default mappings:

Example:

import "@acton/testing/expect"
import "@contracts/types"
import "@wrappers/Counter.gen"

These defaults are written into Acton.toml by project scaffolding commands such as acton new and by acton init only when it creates a missing manifest. The exact path depends on the scaffold layout: standard templates use contracts/, tests/, and wrappers/, while --app scaffolds use contracts/src/, contracts/tests/, and contracts/wrappers/.

Acton does not silently recreate deleted folders during normal workflows. To recreate missing folders, manually restore them from Git within the Git-managed project.

Prefix resolution rules

• Exact Match: Acton matches the first part of the path (before the first slash) against the defined mappings. For example, in import "@core/math", it looks for the @core mapping.
• Normalization: If a mapping key doesn't start with @ (preferred), Acton automatically prepends it.
• Relative Paths: Relative paths in mappings are resolved relative to project root for the current invocation.

Additional properties

Acton allows adding arbitrary metadata fields to any section of Acton.toml. These fields are ignored by Acton itself but can be used by third-party tools or for project-specific metadata.