How to adopt sub-second finality

The TON Core team is releasing Catchain 2.0, a consensus upgrade targeting sub-second finality to bring the on-chain experience closer to Web2 responsiveness.

However, a faster blockchain does not automatically improve user experience. This upgrade delivers the speed — projects must adapt their apps to surface it to users.

Current status

The upgrade targets a block interval of 200–400ms (down from ~2.5s on current mainnet), roughly 2.5–5x throughput in blocks per second, and a finalization lag of ~1s versus the current ~10s.

Network	Block interval	Blocks per second	Finalization lag
Mainnet today	~2.5s	~0.4	~10s
Testnet today	~450ms	~2.2	~1–2s
Mainnet target	200–400ms	~2.5–5	~1s

Together with consensus update, there is a Streaming API v2 from TON Center to receive transaction status updates with 30–100ms latency.

Testnet operates close to the target speed and is the primary environment for testing projects.

Example of sub-second user experience in action

MyTonWallet and tonscan.org already use Streaming API v2 on both mainnet and testnet to deliver transaction status updates with low latency. This has already nearly halved the reaction time in these products, even though sub-second finality is not yet enabled on mainnet.

What projects need to do

Wallets and dApps

A faster chain alone does not reduce end-to-end latency if the application continues to use HTTP polling. In this case, transaction status updates can still arrive 10 seconds or more after inclusion. To support sub-second latency, deliver transaction updates through streaming APIs instead of polling.

Actions

• Switch to TON Center Streaming API v2. Handle all four transaction statuses: "pending", "confirmed", "finalized", "trace_invalidated".

• If Streaming API cannot be used, reduce polling intervals and adjust assumptions about transaction timing. Interfaces should be designed to expect results in under 1 second.

Self-hosted nodes, liteservers, and TON Center instances

Actions

1. Update all self-hosted components to the versions that include Catchain 2.0 support:

   • TON node and liteserver – update to the latest release before mainnet activation.
   • Self-hosted TON Center – update to the version with Streaming API v2 support.

2. After updating, connect each component to testnet and verify that it operates correctly under the higher block rate. Do not wait for mainnet activation; issues identified late are harder to resolve.

Indexers

Indexers must process up to 10x more blocks per second without accumulating lag. If it was tuned for 2.5s block intervals, it will fall behind under 200-400ms intervals.

Actions

1. Connect the indexer to testnet.

2. Run for 30+ minutes.

3. Measure lag continuously.

4. If lag increases, identify and resolve bottlenecks (e.g., database writes, network, parsing) before mainnet activation.

5. Generate the typical mainnet load profile on testnet and verify that the indexer keeps up. See Expected user experience and Test on testnet for guidance.

Expected user experience

Behavior without Streaming APIs

Even if the blockchain produces blocks up to 10x faster, apps that do not use Streaming APIs still:

• Poll HTTP endpoints at fixed intervals.
• Wait for full block finalization before updating the UI.
• Show delays of 10+ seconds to users.

A typical sequence for polling-based integrations:

1. 0s – user clicks “Send”;
2. ~0.4s – transaction included in a shard block;
3. ~0.8s – shard block committed to masterchain;
4. ~10s – UI updates on the next HTTP polling request.

User perception: “You said the blockchain is fast. Why does my transfer still take 10 seconds?”

Behavior with Streaming APIs

1. 0s – user clicks “Send”;
2. ~0.1s – "pending" status with expected outcome is displayed;
3. ~0.4s – transaction included in a shard block and "confirmed" status is displayed;
4. ~0.8s – shard block committed to masterchain and "finalized" status is displayed.

Why this matters

The sub-second finality update rollout requires coordinated changes across the ecosystem:

• TON Core delivers faster block production and low-latency APIs.
• Ecosystem projects must adapt indexers and UI layers to surface this speed.

If apps do not adapt, the upgrade appears ineffective, even when the underlying system operates correctly. Projects that are ready before the mainnet rollout will demonstrate the intended behavior and user experience.

How to integrate

Recommended stack

For projects building on TON:

• Streaming API: TON Center Streaming API v2.
• Data layer: TON Center v3.
• SDK: AppKit for balances, tokens, NFTs, and contract interactions.
• Finality: wait "finalized" status for critical flows.

Public liteserver

Public liteservers are available for both mainnet and testnet. Use global config files to discover and connect to them:

• Mainnet: ton.org/global.config.json
• Testnet: ton.org/testnet-global.config.json

Self-hosted liteserver

If a liteserver node is self-hosted, ensure it is updated before mainnet rollout.

Actions

Confirm that the node version supports the new consensus.

TON Center Streaming API v2

TON Center Streaming API v2 provides:

• Push-based delivery of transaction status updates.
• Four statuses: "pending", "confirmed", "finalized", "trace_invalidated".
• Latency: 30–100ms from chain event to the client.

API token

• For testing purposes, any valid token for TON Center allows for 2 concurrent streaming connections.
• For production usage, higher connection limits require a paid plan.

Endpoints

SSE and WebSocket are available. Choose based on the stack:

• SSE – browser-friendly, server-to-client only (unidirectional).
• WebSocket – bidirectional, allows dynamic subscribe and unsubscribe after connection.

Protocol	Testnet URL	Mainnet URL
SSE	https://testnet.toncenter.com/api/streaming/v2/sse	https://toncenter.com/api/streaming/v2/sse
WebSocket	wss://testnet.toncenter.com/api/streaming/v2/ws	wss://toncenter.com/api/streaming/v2/ws

Transaction status flow to implement

1. Initiate the transaction after the user’s request.

2. Subscribe to the sender or recipient address through the Streaming API before or immediately after sending.

   • On pending, display a processing indicator.
   • On confirmed, optionally display optimistic success.
   • On finalized, display confirmed success and update state.
   • On trace_invalidated, discard a cached trace and recheck the status manually.

Configure min_finality

The min_finality parameter controls the earliest status delivered. The default value is "finalized".

If the parameter is omitted, only "finalized" events are delivered. "pending" and "confirmed" updates are not sent.

Use case	min_finality value
Send flow (real-time feedback)	"pending" to receive four status updates.
History and balance display	"finalized" to work only with settled data.

Example subscription (send flow):

{
  "accounts": ["<ADDRESS>"],
  "min_finality": "pending"
}

WebSocket keepalive

• Send a ping every 15 seconds to keep the connection alive.
• SSE connections receive automatic server-side keepalive (: keepalive) every 15 seconds; no client action required.

AppKit for app developers

AppKit provides ready-to-use components for frontend applications. It handles out of the box:

• TON balance for any address;
• Jetton balances and metadata;
• NFT holdings;
• Contract state reads;
• Transaction sending, including jetton transfers.

Test on testnet

Testnet runs at sub-second speed (200–400ms block finality). Run tests here before enabling sub-second changes on mainnet.

Testnet endpoints

Use the public API endpoints overview for testnet endpoints, including TON Center v2 and v2.

How to get test tokens

• For the standard faucet, up to 2 TON per hour, use Telegram Testgiver TON bot.
• For larger allocations up to 5,000 TON, use the request form.

What to test

Perform the following tests to validate UX and wallet behavior.

For indexer teams

1. Connect indexer to testnet.
2. Run for 30+ minutes under normal conditions.
3. Measure indexer lag as the time between block production and indexer processing.
4. Ensure lag remains below 500ms and no backlog accumulates.

For UX and app teams

1. Connect to testnet endpoints.
2. Initiate a TON transfer.
3. Observe three statuses in sequence: "pending" → "confirmed" → "finalized".
4. Measure time from transaction send to "finalized". It should be under 1 second on testnet.
5. Test "trace_invalidated" path: intentionally send a malformed transaction and confirm that UI handles it correctly.

For wallet teams

1. Verify balance updates reflect within 1 second of "finalized" status.
2. Verify transaction history updates in real time.

Resources

• Announcement, Telegram channel
• TON Core deployment progress, Telegram channel
• TON Core R&D technical overview, Telegram channel
• UX approaches for sub-second finality, Telegraph
• Streaming API v2 specification, Gist
• TON Center API overview and endpoints
• AppKit documentation

Get support

Use the sub-second finality support chat for questions about this upgrade.