Acton.toml

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

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 (for example [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] Section

Defines the metadata for your Acton project.

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] Section

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 = "0.3.2"

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

[contracts] Section

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

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] Section

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 cwd-relative unless you pass absolute paths. Precompiled .boc contracts are skipped for ABI and Fift output.

[wrappers] Section

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] Section

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] Section

Configures defaults for acton localnet.

Example:

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

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

[test] Section

Configures the behavior of acton test.

TonCenter 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] Section

Configures default coverage behavior for acton test.

[test.fuzz] Section

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

[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.

fail-on-diff is used together with baseline comparison mode (acton test --baseline-snapshot <FILE>).

[lint] Section

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 Linting.

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/types, but lint diagnostics for them are hidden. When you pass an explicit target to acton check (contract name or file path), that target is checked even if it matches exclude. Compiler errors are never hidden by exclude. Project-wide discovery still 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 are never 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 (see Linting Configuration). Suppressions use rule names (for example unused-variable) and do not affect compiler/parser diagnostics (C001).

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

You can override lint levels for specific contracts by creating a subsection with the contract's name (the NAME from [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] Section

Defines network settings used by --net/--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://localhost: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"

You can use these networks in commands like:

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

[scripts] Section

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] Section

Allows defining path aliases for the Tolk compiler, similar to @stdlib. These mappings let you import 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, you can use these mappings in your Tolk source files:

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 updated with acton init usually contain these default mappings:

Example:

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

These defaults are written into Acton.toml by project scaffolding commands such as acton new and acton init. The exact path depends on the scaffold layout: standard templates use contracts / tests / wrappers, while --app scaffolds use contracts/src / contracts/tests / contracts/wrappers. If you remove them manually, Acton does not silently recreate them during normal compilation; add them back explicitly or rerun acton init.

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.