Masterchain

Caution

Masterchain addresses are treated as invalid unless the masterchain option in the configuration file is set to true.

In TON Blockchain, a special chain called “masterchain” is used to synchronize message routing and transaction execution, so that nodes in the network can fix a particular point in a multi-chain state and reach a consensus about that state.

Masterchain stores the network configuration and the final state of all workchains. It carries fundamental protocol information, including current settings, a list of active validators and their stakes, active workchains, and associated shardchains. Most importantly, it maintains a record of the latest block hashes for all workchains and shardchains, enforcing consensus across the network.

How contract is protected from masterchain

Tact enforces all contracts to use the basechain, which is the default workchain with ID $0$. This is done to prevent masterchain addresses from being used in the contract.

Any attempts to point to masterchain or otherwise interact with it without enabling masterchain support throw an exception with exit code 137: Masterchain support is not enabled for this contract.

That is, accidental deployments to the masterchain, receiving messages from masterchain accounts, sending messages to such accounts, and using masterchain addresses or its chain ID ($-1$) are all prohibited by default.

Enabling masterchain support in compilation options

Caution

Most contracts don’t need to be deployed on a masterchain or have any interactions on a masterchain. That’s because the masterchain is primarily used for voting or storing libraries. If you don’t need to partake in those things, you don’t need to enable masterchain support.

If you really do need masterchain support, the simplest and recommended approach is to modify a tact.config.json file in the root of your project (or create it if it didn’t exist yet), and set the masterchain property to true.

If you’re working on a Blueprint-based project, you can enable masterchain support in the compilation configs of your contracts, which are located in a directory named wrappers/:

wrappers/YourContractName.compile.ts

import { CompilerConfig } from '@ton/blueprint';

export const compile: CompilerConfig = {
  lang: 'tact',
  target: 'contracts/your_contract_name.tact',
  options: {
    masterchain: true, // ← that's the stuff!
  }
};

However, tact.config.json may still be used in Blueprint projects. In such cases values specified in tact.config.json act as default unless modified in the wrappers/.