Migrate from MyLocalTon to Localton and Studio

This guide covers MyLocalTon (MLT) desktop and mylocalton-docker. Localton runs a local TON blockchain with real validators and TON Center APIs. Acton manages its lifecycle, and Studio provides the browser interface.

You can keep your existing JavaScript or TypeScript application and deployment scripts. Changing the development network does not require a contract rewrite.

The transition creates a new blockchain. MLT databases, Docker volumes, and Time Machine snapshots have no direct import path into Acton. An identical global_id does not reproduce the old zerostate, block hashes, validator keys, or transaction history.

What changes with Localton and Studio

Studio brings network operations and application development into one project workspace. The CLI and Studio manage the same localnet catalog for that project.

The following capabilities are useful during migration and subsequent development:

• Several named environments. Keep independent networks for different configurations and tests. Each network has its own state, endpoints, nodes, and snapshots.
• A reusable genesis file. Store the required parameters in genesis.toml. Studio imports and exports the file, explains units, and highlights invalid values and related fields.
• Connections for existing tools. Copy Acton or @ton/ton examples from Connect environment. Studio proxy URLs also expose client requests in API calls.
• Contract inspection in the same workspace. Use Explorer for accounts, blocks, messages, tokens, and traces. Contracts connects deployed contracts with available project sources and ABI artifacts when their code matches.
• Project wallets and signing. Use configured development wallets across environments. Studio provides funding, transfers, and TON Connect sessions for the selected environment.
• Controlled test state. Import active accounts or use Admin actions to change balances, code, data, and account status. Snapshots provide restore points before these changes.
• Node and workload controls. Add full nodes or validators, inspect elected sets, generate bounded activity, and optionally copy local blockchain data to reduce synchronization time.

Select Localnet for validator, consensus, and indexer workflows. Simulator is a separate environment type with virtual time, manual mining, and public-network forks.

Decide what to preserve

Before changing the old installation, save its configuration and deployment inputs:

• For MLT Docker, retain .env, Compose files, image versions, modified genesis templates, and the existing volumes.
• For MLT desktop, retain its data directory, settings.json, and any custom TON binary configuration.
• Record the network ID, wallet versions and IDs, account addresses, and the parameters that your tests depend on.
• Retain development wallet credentials separately from public configuration. An address or public key alone cannot sign transactions.
• Save deployment scripts, contract code, initialization data, and off-chain metadata files or URLs.

For an account export, stop application writes and activity generators first. Wait for pending messages to settle, then read related accounts at one source block. Stopping all MLT services also stops its API, so export accounts before doing that.

Keep MLT available until you finish the transition checks. Separate ports let both networks run on the same machine, subject to Docker resource limits.

Prepare Acton and Docker

Install Acton, then select a trunk build with custom genesis support:

acton up --trunk
acton --version

Check Docker and Compose:

docker info
docker compose version

In your existing project directory, initialize Acton if Acton.toml is absent:

acton init

Run later CLI and Studio commands from this project. The default localnet catalog is <project>/.acton-localnet; a different project directory selects a different catalog. A custom --state-dir must remain the same across CLI commands.

Docker stores blockchain databases and snapshots in volumes. Copying .acton-localnet alone does not back up those databases. Allocate disk space for the network, additional nodes, the V3 index, snapshots, and temporary copies.

Acton selects its Localton image automatically. It uses the TON v2026.10 toolchain in the current trunk implementation. Older MLT images can use different VM and consensus versions, so compare behavior as well as configuration values.

ACTON_LOCALNET_IMAGE selects a compatible custom Localton image for a new runtime. Set it before starting the CLI service or Studio. An MLT image does not implement Acton's runtime contract. An existing runtime retains its saved image selection.

On Windows, use the WSL installation workflow and a Docker engine accessible from that environment. MLT's native Windows packaging does not transfer to Localton.

Translate the genesis configuration

Create a separate genesis.toml. Acton does not import the MLT .env file. Copy only the values that your tests require.

This example retains the MLT network identifier and a 300 ms Simplex target:

global_id = -217
simplex_target_rate_ms = 300

Missing fields, including fields inside partial tables, use Localton defaults. Unknown fields are errors. These defaults are suitable for local development, but they do not reproduce every MLT parameter.

The following differences come from the referenced MLT Docker configuration and the current Localton defaults:

The block interval is a consensus target. Hardware, load, and elections affect actual block production. A matching interval alone does not produce matching fees or transaction hashes.

Keep all root fields before the first TOML table. A field after [storage], for example, belongs to storage until the next table header.

Studio highlights invalid values and related fields. See the genesis reference for validation rules.

Prepare development wallets

Import an existing development mnemonic before selecting startup accounts. This interactive example uses Wallet V4R2:

acton wallet import --name deployer --version v4r2 --local

Choose the version that matches your existing wallet. The wallet guide covers mnemonic schemes and secure storage.

Importing credentials restores signing access. It does not restore the old network's balance, deployment state, or transaction history. A raw MLT .pk file is not a mnemonic and cannot be passed to mnemonic import.

Studio project wallets use mnemonics. If you only have a .pk file, keep an external signer that supports that key and connect it to Localton. Alternatively, transfer contract ownership to a mnemonic wallet before export, if the contract supports this operation, or redeploy with that wallet as owner. There is no general conversion from a private key to the original mnemonic.

To preserve an address, match all address inputs:

An explicit project wallet-id overrides the network default. Check the resulting raw address in the selected environment before funding or signing. Bounceable and non-bounceable strings can represent the same raw address.

Selected startup wallets receive 100 GRAM when Acton creates the network. This allocation is separate from faucet_balance and the built-in validator wallet allocations. An existing network does not fund newly configured wallets or replenish balances on restart.

For parallel tests, initialize the required project wallets at creation. Wait for additional node creation to finish before requesting manual faucet transfers. Concurrent bootstrap grants currently can reuse the faucet sequence number, and submission success does not prove that the destination received funds.

Create the replacement network

For a genesis account import, export the source accounts before this step. The CLI example below explains where to add the resulting accounts.json.

acton studio

acton localnet start mlt-dev --genesis genesis.toml \
  --port-base 19000 --accounts "" --detach
acton localnet status mlt-dev

acton localnet create mlt-prepared --genesis genesis.toml --accounts ""
acton localnet start mlt-prepared --detach

Acton saves the resolved genesis with the network. Later edits to the input file do not change that network. Create a new network to use another genesis. Reusing a saved name with creation flags is rejected instead of silently replacing its configuration.

ACTON_LOCALNET_GENESIS can supply the file path instead of --genesis. An explicit path takes precedence. Acton does not automatically discover a file named genesis.toml.

Explicit timing flags override the file, including dependent election intervals. To preserve imported timing values, omit those flags. A resolved export makes later comparisons easier because defaults can change between Acton versions.

The first start can require image downloads and indexer initialization. Wait for Running and inspect Network → Health before deploying. A running Docker container alone does not prove that the chain and its APIs are ready.

Add nodes from local blockchain data

MLT can copy genesis database files to speed up a new node's synchronization. Localton provides an optional equivalent for nodes in the same managed network:

acton localnet node mlt-dev add validator-b --validator --copy-state

In Studio, open Network → Nodes → Add node and select Copy blockchain data. Leave it unchecked for normal network synchronization.

Acton stops the network while it copies genesis blockchain data, then restarts it and joins the new node. The new node generates independent keys and synchronizes any remaining blocks. The copy requires additional disk space; its duration depends on database size and storage speed.

API requests and transaction submission are interrupted during the stop. Use ordinary synchronization if the existing network must remain available. The new node does not share a live writable database with genesis.

This option copies data between Localton nodes in the same managed network. It does not import an MLT database, volume, or Time Machine snapshot, and it does not copy the V3 index.

Manage election participation

Without --validator, the new process is a full node. With it, the node joins elections after synchronization and wallet preparation. A newly added validator is not immediately part of the current elected set.

Read node IDs from the add result or acton localnet status mlt-dev --json. Use the returned ID, not the display name:

acton localnet node mlt-dev leave-validation '<NODE_ID>'

Wait until Network → Validators shows the node outside both the current and next elected sets. Then remove it:

acton localnet node mlt-dev remove '<NODE_ID>' --yes

Leaving validation stops future participation but does not cancel current duties. Studio's Stop node preserves data and stops the process immediately. Stopping enough elected weight can halt the chain, even if other containers remain healthy. Use removal's --force only for scenarios that intentionally interrupt consensus.

Connect applications and signing tools

Read the endpoints from acton localnet status mlt-dev, or open Home → Connect environment in Studio. Integrate retains the connection examples.

For the CLI network created with --port-base 19000, the host ports are:

Use the reported addresses if Acton selected ports automatically. Do not carry over MLT port numbers, Docker service names, or an old global.config.json.

Choose direct endpoints or Studio proxy URLs

Direct endpoints connect to the managed localnet. Studio proxy URLs route requests through Studio and associate them with the selected environment. They also support request inspection in API calls.

Copy proxy URLs from Connect environment rather than constructing them from a network name. The environment ID keeps these URLs stable across renames and runtime restarts. The Studio server must remain available for proxy requests. Direct endpoints are useful for standalone CLI and CI workflows.

Changing the selected Studio environment does not rewrite an already running application's endpoint or a CLI command's network selector.

[networks.mlt-dev]
global-id = -217
api.v2 = "http://127.0.0.1:19002/api/v2"
api.v3 = "http://127.0.0.1:19003/api/v3"

acton script scripts/deploy.tolk --net custom:mlt-dev

import {TonClient} from "@ton/ton"

const client = new TonClient({
  endpoint: "http://127.0.0.1:19002/api/v2/jsonRPC",
})

const masterchain = await client.getMasterchainInfo()
console.log(masterchain)

const response = await fetch("http://127.0.0.1:19003/api/v3/transactions?limit=1")
if (!response.ok) {
  throw new Error(`Localnet V3 returned HTTP ${response.status}`)
}
const page = await response.json()
console.log(page.transactions)

WALLET_NETWORK_ID=-217 npx blueprint run deployCounter \
  --custom http://127.0.0.1:19002/api/v2/jsonRPC \
  --custom-version v2 --custom-type custom --mnemonic

curl --fail http://127.0.0.1:19000/localhost.global.config.json \
  --output localton.global.config.json

lite-client -C localton.global.config.json -c last

Connect a dApp through TON Connect

Studio signs and submits transactions approved through TON Connect. Your application's RPC endpoint controls its reads and any signed messages it submits directly. Both must refer to the same environment.

1. Open the target environment's Wallets page and check the funded project wallet address.
2. Open the connection dialog in the dApp and copy its TON Connect URL.
3. Paste the URL into Connect URL in Studio and select Handle request.
4. Select the intended development wallet and approve the connection.
5. Send a small test transaction, approve it in Studio, and inspect it in the same environment's Explorer.

Disconnect old sessions before changing the signing environment. Public wallet applications do not automatically connect to your local validators because your dApp's RPC URL changed.

Connect from another container or machine

The managed ports bind to the host's 127.0.0.1. In another container, 127.0.0.1 refers to that container. On a phone or another computer, it refers to that device.

For a containerized client, provide a route to the Docker host and check reachability from inside the client container. On Docker Desktop, host.docker.internal identifies the host. Linux setups need an appropriate host-network or forwarding arrangement; a hostname substitution alone does not expose a loopback-only service.

For example, a client container on a native Linux Docker host can use host networking. Replace my-client-image with your application image:

docker run --rm --network host \
  --env TON_RPC_URL=http://127.0.0.1:19002/api/v2/jsonRPC \
  my-client-image

This example assumes your application reads TON_RPC_URL. Host networking makes the host's loopback ports accessible to that container.

For a remote HTTP client, forward V2 and V3 through SSH. Run this on the client machine and replace user@docker-host:

ssh -N \
  -L 127.0.0.1:19002:127.0.0.1:19002 \
  -L 127.0.0.1:19003:127.0.0.1:19003 \
  user@docker-host

While the tunnel is open, the V2 and V3 examples work unchanged on that machine. The client ports must be free.

LiteAPI needs its own TCP forwarding and a configuration containing the reachable address and port. MLT's EXTERNAL_IP and embedded file-server configuration do not migrate automatically. Forward only the services the client needs.

Recreate contract state

For deployment tests, run the existing deployment and initialization scripts against the new endpoints. Existing MLT addresses have no account state in the new network by default. Update application configuration if new owner addresses or initialization data produce different contract addresses.

For state-dependent tests, import selected accounts instead. A genesis import accepts complete active basechain ShardAccount bags of cells (BoCs). Save them as a JSON array of hexadecimal strings in accounts.json. Add --accounts-file accounts.json when you create the replacement network.

If you already created mlt-dev, use the existing-network import described below or create another named network and update your client endpoints. Restarting mlt-dev with an account file does not apply a genesis import to it.

This copies account state, not source transaction history or validator databases. Include contract dependencies explicitly. Plain addresses and contract data cells are not complete account imports. See account imports for the required format.

Export from a compatible MLT API

The source API must support getShardAccountCell. The C++ V2 v2.1.7 image in the referenced MLT Docker configuration lacks this endpoint. You can attach a newer API to that source network without replacing its services:

The following command uses the temporary exporter's port. If your existing source API already supports the method, use its V2 URL instead. Replace the address and masterchain sequence number with your MLT values:

curl --fail --get http://127.0.0.1:18082/api/v2/getShardAccountCell \
  --data-urlencode 'address=<ACTIVE_BASECHAIN_ADDRESS>' \
  --data-urlencode 'seqno=<SOURCE_MASTERCHAIN_SEQNO>' \
  --output mlt-account.json

Read the source masterchain sequence number from its getMasterchainInfo response. Use the same block for related account exports. The source must still retain that state.

The response contains a base64 BoC in result.bytes. Convert it to the hexadecimal array expected by --accounts-file:

import {readFileSync, writeFileSync} from "node:fs"

const response = JSON.parse(readFileSync("mlt-account.json", "utf8"))
if (!response.ok) {
  throw new Error(response.error ?? "Account export failed")
}

const boc = Buffer.from(response.result.bytes, "base64")
writeFileSync("accounts.json", JSON.stringify([boc.toString("hex")], null, 2) + "\n")

node convert-account.mjs

This example writes one account. For several accounts, put their distinct hexadecimal BoCs in the same array. Acton checks the account format, active status, workchain, and duplicate addresses.

Preserve dependencies and application assumptions

• Include jetton masters and the required jetton wallets together. Include NFT collections and the items that the scenario uses.
• Retain off-chain metadata servers and assets. An account import preserves stored URLs but does not copy their contents.
• Supply required libraries and other referenced contracts. Localton does not load missing dependencies from MLT on demand.
• Retain access to the owner or administrator keys. Importing a contract does not grant signing access or change its owner.
• Check stored deadlines, wallet sequence numbers, and contract-specific network IDs. Account import does not rewrite contract data for the new clock or network.
• Exclude imported wallet addresses from Startup accounts. A startup allocation and a preserved wallet account are different initial states for the same address.

Genesis rebuilds blockchain bookkeeping for the new network. The import preserves contract code, data, libraries, and balance, but it does not reproduce the old message queue or block history. A wallet's sequence number stored in its contract data remains part of that imported data.

The genesis import path does not accept masterchain system accounts, frozen accounts, or uninitialized accounts. MLT's built-in masterchain wallets therefore do not fit this import path. Use development credentials and fresh funding, or recreate the application state through scripts.

For an existing Localton network, use Import accounts or Admin actions. These operations pause the network and apply a hardfork. They are not ordinary transfers or contract deployments. Save a snapshot before replacing live account state.

Account for workflow differences

Configuration changes after creation

Use Network → Config to inspect current on-chain values and submit supported changes. Editing genesis.toml changes only the input for a future network. Exporting the creation configuration does not capture later on-chain changes.

MLT's Config Update service and Studio's configuration editor operate on chain state. They are separate from Docker process configuration. Values such as CUSTOM_PARAMETERS, HEALTHCHECK_INTERVAL, THACPP_*, and Compose CPU limits are not genesis fields.

Keep custom genesis inputs and the Acton version with your test project. Record later configuration changes in scripts or retain a Localton snapshot that includes them.

Activity and test traffic

Activity supports transfers, batches, jetton mint/transfer/burn, and NFT mint/transfer. It adds bounded duration, concurrency, scenario weights, and progress in the same workspace. The localnet service owns a run, so closing the page does not stop it.

MLT multisig, Highload V3, subscription, library-reference, and NFT sale scenarios still need separate scripts. SPAM_* and data-generator PERIOD values have no direct import. Configure the intended workload in Studio, then compare confirmed outcomes and node/indexer load.

Stopping Activity stops new work; it does not undo messages already submitted. Wait for those messages before exporting account state or taking a baseline snapshot.

Snapshots, restart, and reset

Localton snapshots capture its blockchain state and node topology. Creation pauses a running network, saves the archive, and resumes it. A stopped network stays stopped.

Restore replaces current state and rebuilds the V3 index. During rebuilding, an indexed query can lag behind the restored chain. MLT Time Machine archives, instance branches, and PostgreSQL snapshots cannot be imported. Studio has no Time Machine branch graph or Localton archive import/export controls.

Create a baseline after the migration checks:

acton localnet snapshot mlt-dev create migrated-baseline
acton localnet snapshot mlt-dev list

Use the returned snapshot ID to restore it:

acton localnet snapshot mlt-dev restore '<SNAPSHOT_ID>' --yes

After restore, check chain and API readiness before resuming scripts. If Acton used a temporary control service for an offline restore, start the network again with acton localnet start mlt-dev --detach.

Stopping and restarting preserves balances, contracts, and history. It does not reset the chain or repeat startup funding. To return to a test baseline, restore a snapshot. To use another genesis, create a new named network.

Deleting an environment removes its managed blockchain data and snapshots. Use the environment's deletion controls instead of a global Docker prune. Keep the original MLT data until the replacement passes your tests.

Resource use and deployment topology

Localton's managed stack always includes the indexer services. MLT profiles such as indexer-minimal, per-service CPU quotas, and independent service toggles have no equivalent Studio creation controls.

Additional validator databases, state copies, snapshot archives, and index rebuilding all need disk space. Stop releases runtime resources while retaining those files. Use Network → Health and the diagnostic logs to distinguish a chain failure from an indexer failure.

MLT's web faucet options, including reCAPTCHA and giveaway limits, do not configure Studio's development faucet. A shared public faucet is a separate deployment concern. Native Localton has separate binary configuration documented in its README; MLT's TON_IMAGE and TON_BRANCH cannot be copied into genesis.toml.

Diagnose migration problems

Inspect the network and its operation log:

acton localnet status mlt-dev --json
acton localnet logs mlt-dev --tail 200

Studio provides diagnostic details and paths to full logs for failed operations. Preserve those logs before deleting state. A PostgreSQL failure, for example, is not necessarily a genesis error.

Check the transition

Before you retire the MLT network:

• Check node, V2, V3, and indexer readiness under Network → Health.
• Compare the parameters your tests use under Network → Config.
• Check project wallet addresses and balances in the selected environment.
• Run a contract getter and send a wallet transfer through the migrated application.
• Open the transaction and trace in Explorer after the indexer catches up.
• For imported contracts, compare code, storage, balances, dependencies, and owner access with the source.
• Stop and resume the network, then check that its account state remains available.
• Restore a Localton snapshot and repeat one representative application scenario.

For the CLI example, resume the saved network without creation flags:

acton localnet stop mlt-dev
acton localnet start mlt-dev --detach

If you selected the genesis file through ACTON_LOCALNET_GENESIS, unset that variable before resuming.

Save a Localton snapshot as the starting point for subsequent experiments.