Project Configuration

achronyme.toml project manifest reference.

Every Achronyme project can have an achronyme.toml file at its root. This file configures defaults for CLI commands, eliminating the need to pass flags repeatedly.

Quick start

ach init my-circuit
cd my-circuit
ach run              # reads entry from achronyme.toml

Config resolution

The CLI searches for achronyme.toml by walking up from the input file’s directory (or the current working directory if no file is specified). The first match is used.

Values are resolved with this precedence:

CLI flags (explicit)  >  achronyme.toml  >  hardcoded defaults

Use --no-config to disable achronyme.toml loading entirely.

Full schema

[project] — Project metadata

[project]
name = "my-circuit"           # Required. Must match [a-zA-Z_][a-zA-Z0-9_-]*
version = "0.1.0"             # Required. Semantic versioning (MAJOR.MINOR.PATCH)
description = "A ZK circuit"  # Optional
license = "MIT"               # Optional. SPDX identifier
authors = ["Alice <a@b.com>"] # Optional
entry = "src/main.ach"        # Optional. Default entry file for run/compile/circuit/disassemble

When entry is set, you can omit the file path from CLI commands:

# Instead of:
ach run src/main.ach

# Just:
ach run

[build] — Compilation settings

[build]
backend = "r1cs"          # "r1cs" (default) or "plonkish"
optimize = true           # Enable IR optimization passes (default: true)
error_format = "human"    # "human" (default), "json", or "short"

[build.output] — Output paths

[build.output]
r1cs = "build/circuit.r1cs"      # Default .r1cs output path
wtns = "build/witness.wtns"      # Default .wtns output path
binary = "build/{name}.achb"     # Default .achb output path ({name} = project.name)
solidity = ""                    # If non-empty, generate Solidity verifier
plonkish_json = ""               # If non-empty, export Plonkish JSON

The {name} template variable is replaced with project.name.

[vm] — Virtual machine settings

[vm]
prove_backend = "r1cs"
max_heap = "256M"
stress_gc = false
gc_stats = false

# Host capabilities are denied unless explicitly granted.
allow_read = ["data"]
allow_write = ["output"]
allow_connect = ["127.0.0.1:9000"]
allow_listen = []

# Structured-concurrency and bounded-I/O limits.
max_tasks = 64
max_resources = 32
max_task_scopes = 16
max_pending_native_requests = 32
max_retained_task_results = 64
max_channels = 32
max_channel_operations = 128
blocking_workers = 4
blocking_queue_capacity = 64

Relative paths in allow_read and allow_write are resolved from the project root. Supplying any repeatable capability flag on the CLI replaces that capability’s manifest list for the invocation. Network grants accept numeric IP:PORT endpoints; hostname resolution is not implied.

[proving] — Proving-key trust

Proof generation is fail-closed by default. Choose exactly one key source when a program needs to create a proof:

[proving]
# Production: load ceremony-derived artifacts from this project-relative directory.
trusted_key_dir = "ceremony/keys"

# Development only; do not combine with trusted_key_dir.
# insecure_dev_setup = true

trusted_key_dir and insecure_dev_setup = true are mutually exclusive. CLI trust flags override the manifest. With neither source configured, execution may compile circuits and verify detached artifacts, but any attempt to generate a proving key fails rather than silently creating an unsafe local setup.

[circuit] — Circuit settings

[circuit]
prime = "bn254"      # Prime field: "bn254" (default), "bls12-381", or "goldilocks"

The prime field is the manifest equivalent of the global --prime flag. If --prime is explicitly passed on the CLI, it overrides this value.

Public and witness inputs are not configured here — they come from the in-source public and witness declarations (or the --public / --witness CLI flags). This section is validated with deny_unknown_fields, so any other key (such as public or witness) is rejected with a hard error.

[circom] — Circom library search paths

[circom]
libs = ["vendor/circomlib/circuits", "third_party/circuits"]

Paths are resolved relative to the project root (the directory holding achronyme.toml). Every subcommand that parses .circom sources — ach circom, ach run, ach circuit — will look in each libs entry when resolving include "file.circom"; directives.

CLI -l/--lib flags append to the TOML list rather than replacing it, so ach circom -l extra/ extends libs for a one-off invocation without editing the manifest.

# With libs = ["vendor/circomlib/circuits"] in achronyme.toml:
ach circom circuit.circom                      # only vendor/ searched
ach circom circuit.circom -l extra/circuits    # vendor/ and extra/ both searched

Use this section to version-control where your circom dependencies live instead of scattering -l flags across scripts.

Minimal example

[project]
name = "multiply"
version = "0.1.0"

[build]
backend = "r1cs"

Full example

[project]
name = "merkle-prover"
version = "0.2.0"
description = "Merkle tree membership proof circuit"
license = "MIT"
entry = "src/main.ach"

[build]
backend = "r1cs"
optimize = true
error_format = "human"

[build.output]
r1cs = "build/circuit.r1cs"
wtns = "build/witness.wtns"
solidity = "build/Verifier.sol"

[vm]
prove_backend = "r1cs"
max_heap = "512M"
allow_read = ["data"]
allow_write = ["build"]
max_tasks = 64
max_resources = 32
max_channels = 16
max_channel_operations = 64

[proving]
trusted_key_dir = "ceremony/keys"

Validation

The CLI validates the TOML file on load:

• project.name must match [a-zA-Z_][a-zA-Z0-9_-]*
• project.version must be valid semver (MAJOR.MINOR.PATCH)
• build.backend must be "r1cs" or "plonkish"
• build.error_format must be "human", "json", or "short"
• vm.prove_backend must be "r1cs" or "plonkish"
• vm.max_heap must be a valid size string if non-empty
• proving.insecure_dev_setup and proving.trusted_key_dir cannot both be set
• proving.trusted_key_dir cannot be empty
• circuit.prime must be "bn254", "bls12-381", or "goldilocks"
• project.entry must end in .ach or .achb
• circom.libs entries must exist (resolved at load time, relative to project root)
• Unknown fields are rejected (forward compatibility via explicit sections)