FunC to Tolk migration

Use the func2tolk skill to migrate a FunC and TypeScript project to Tolk and Acton

The func2tolk skill helps a coding agent migrate an existing FunC project to idiomatic Tolk code with Acton as the all-in-one toolchain.

Use it when a repository already has .fc or .func contracts, TypeScript wrappers, TypeScript tests, deployment scripts, or fixture-based checks. The skill will attempt to port FunC contracts to Tolk and add Acton-native tests, scripts, and wrappers.

The skill uses the acton func2tolk command, which is a converter of FunC code to Tolk, not a full migration by itself. Treat the converted code as a draft, then refactor and modernize the code, preserving old TL-B layouts, opcodes, error codes, getter shapes, send modes, and bounce behaviors.

Install the skill

Select the func2tolk skill when installing Acton dev skills.

After installation, mention the $func2tolk in the prompt when asking the agent to port a repository.

Example prompt

Prompt

Use $func2tolk to migrate this FunC and TypeScript TON project to Tolk + Acton.

Inspect the existing contracts, wrappers, tests, scripts, and fixtures. Preserve TL-B layouts, opcodes, error codes, getter shapes, send modes, bounce behavior, and observable transaction behavior.

Use acton func2tolk if helpful, refactor the draft into idiomatic Tolk, migrate the important tests, generate wrappers, run acton build and acton test, and finish with a short compatibility self-audit.

What the skill does

The skill tells the agent to:

inspect the existing FunC entrypoints, TypeScript wrappers, tests, scripts, fixtures, and package commands before editing;
run acton func2tolk when it is useful for a first-pass conversion;
split the result into Tolk modules such as messages.tolk, storage.tolk, errors.tolk, and contract entrypoint files;
replace manual opcode and slice parsing with tagged message structs, union dispatch, typed storage, typed maps, and createMessage(...) where possible;
migrate important TypeScript tests into tests/*.test.tolk;
generate Acton wrappers for tests, scripts, and optional TypeScript app code;
run Acton build and test commands, then report any remaining compatibility exceptions.

Migration workflow

Manual migration path

The sections below are written for humans who want to understand or perform the migration by hand. When running a coding agent, provide an example prompt and use the rest of this page to review the plan, output, and debugging steps.

Start from a clean branch and capture the old behavior before changing the contract code:

git checkout -b migrate-to-tolk-acton
npm test

If the repository does not already use Acton, initialize it:

acton init

Convert the FunC sources into a draft Tolk output:

acton func2tolk contracts --output contracts-tolk --warnings-as-comments

Then ask the agent to refactor the draft into the Acton project layout. A typical Acton.toml entry looks like this:

Acton.toml

[contracts.MainContract]
display-name = "Main Contract"
src = "contracts/MainContract.tolk"

Once the contract is registered, iterate and gradually refactor it with Acton:

acton build
acton wrapper MainContract --test
acton test
acton check
acton fmt --check

For a TypeScript frontend or existing TypeScript integration tests, generate TypeScript wrappers from the migrated Tolk ABI:

acton wrapper --all --ts --output-dir wrappers-ts

What to expect

A good migration should produce:

an Acton.toml with each migrated contract registered under [contracts];
Tolk contract files with explicit storage, message, and error schemas;
native tests in tests/*.test.tolk that cover the behavior previously checked by TypeScript tests;
generated Tolk wrappers for tests and scripts;
generated TypeScript wrappers when the project still has TypeScript app or integration code;
a report of build and test results plus any compatibility exceptions.

Do not expect the migrated contract to have the same bytecode hash as the FunC contract. The target is TL-B compatibility and observable behavior parity, not identical compiler output.

Debugging

If conversion fails, check that Node.js, npm, and npx are available. Try a single file first and keep converter warnings inline:

acton func2tolk contracts/main.fc --output contracts-tolk/main.tolk --warnings-as-comments

If acton build fails, inspect Acton.toml, import mappings, generated dependency files, and duplicated entrypoints. Rerun with a clean cache:

acton build --clear-cache

If behavior differs from the TypeScript test suite, port the failing case into a Tolk test and compare message bodies, state layout, opcodes, send modes, bounce handling, and unknown-message policy:

acton test --show-bodies --verbose
acton test --save-test-trace

If wrapper generation fails, build first and confirm the contract ABI has the storage, incoming message, and getter declarations expected by the generator:

acton build
acton wrapper MainContract
acton wrapper MainContract --ts --output-dir wrappers-ts

If a compatibility rule forces low-level Tolk code, keep it localized and leave a short comment explaining the FunC layout or behavior being preserved. Common examples include inline body quirks, broad address encodings, remainder payloads, and raw dictionary boundaries.