Skip to content

feat(start-here): add a high-level definition of workchains #1730

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
delovoyhomie wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(start-here): add a high-level definition of workchains #1730

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions start-here.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,13 @@ The other network is _testnet_, and it is used by TON developers to check that t

Usually when the TON blockchain gets an update, it is first deployed to testnet, and then to mainnet after a brief period of testing, so sometimes they may run different software. Also their [configuration](/foundations/config), availability, and throughput might be different.

<Aside
type="note"
title="Key term: workchain"
>
A _workchain_ is a TON blockchain with its own rules and account space. The _masterchain_ holds global configuration, while workchains host most accounts and smart contracts and can be split into shardchains for scalability. Practical note: [addresses](/foundations/addresses/overview#internal-addresses) include the workchain ID, and most apps use workchain 0 (basechain).
Copy link
Collaborator

@Kaladin13 Kaladin13 Jan 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
A _workchain_ is a TON blockchain with its own rules and account space. The _masterchain_ holds global configuration, while workchains host most accounts and smart contracts and can be split into shardchains for scalability. Practical note: [addresses](/foundations/addresses/overview#internal-addresses) include the workchain ID, and most apps use workchain 0 (basechain).
A _workchain_ is a TON blockchain with its own rules and account space. The _Masterchain_ holds global configuration and system smart contracts, while _Basechain_ host most accounts and user space smart contracts and can be split into shardchains for scalability. In future there might be new workchains with there own set of rules and logic. Practical note: [addresses](/foundations/addresses/overview#internal-addresses) include the workchain ID, and most apps use workchain 0 (basechain).

</Aside>

Each network is split into [workchains](/foundations/shards) that can freely interact with each other, but their implementations may differ significantly.

At the moment, there are two workchains: _basechain_ (`workchain_id = 0`) for regular use, and a very similar _masterchain_ (`workchain_id = -1`) for TON's [internal](/payments/overview#transaction-finality) [bookkeeping](/foundations/system). The masterchain follows mostly the same rules, except that using it is more expensive to limit the amount of traffic that interferes with TON's internals.
Expand Down