Signing messages in TON

Overview

Cryptographic signatures are the foundation of access control in TON. Contracts verify signatures on-chain and implement their own policies, enabling flexible designs such as wallet operations, server-authorized actions, gasless flows, multisig, and delegation.

Ed25519 in TON

TON uses Ed25519 as the standard signature scheme. All wallets (v1–v5) and highload wallets rely on Ed25519.

Specification:

• Public key: 256 bits
• Signature: 512 bits
• Curve: Edwards form over Curve25519

See TON Cryptography — Ed25519 for cryptographic details.

The public key is not the wallet address. The address is derived from the contract’s StateInit (code + initial data). Multiple contracts can use the same public key but have different addresses. See Addresses in TON.

Other cryptographic primitives in TVM

TVM exposes additional cryptographic primitives beyond Ed25519. These are useful for cross-chain compatibility and advanced protocols:

• secp256k1 — Ethereum-style ECDSA via ECRECOVER; plus x-only pubkey tweak ops (v9+)
• secp256r1 (P-256) — ECDSA verification via P256_CHKSIGNS / P256_CHKSIGNU
• BLS12-381 — pairing-based ops enabling signature aggregation
• Ristretto255 — prime-order group over Curve25519 for advanced constructions

For details, see TVM changelog or GlobalVersions.md.

This guide focuses on Ed25519, the standard for TON.

What gets signed

Ed25519 signatures in TON work with hashes, not raw data:

1. Off-chain: Serialize message data into a cell → compute its hash (256 bits) → sign the hash with private key → signature (512 bits)
2. On-chain: Contract receives signature and data → recomputes the hash → verifies signature matches the hash and public key

Common signing patterns

Signatures are used in different ways depending on who signs the message, who sends it, and who pays for execution. Here are three real-world examples.

Example 1: Standard wallets (v1–v5)

How it works:

1. User signs a message off-chain (includes replay protection data and transfer details)
2. User sends external message to blockchain
3. Wallet contract verifies the signature
4. Wallet contract checks seqno for replay protection
5. Wallet contract accepts message (pays gas from wallet balance)
6. Wallet contract increments seqno
7. Wallet contract executes the transfer

Key characteristics:

• Who signs: User
• Who sends: User (external message)
• Who pays gas: Wallet contract

This is the most common pattern.

Example 2: Gasless transactions (Wallet v5)

How it works:

1. User signs a message off-chain that includes two transfers: one to recipient, one to service as payment
2. User sends signed message to service via API
3. Service verifies the signature
4. Service wraps signed message in internal message
5. Service sends internal message to user’s wallet (pays gas in TON)
6. Wallet contract verifies user’s signature
7. Wallet contract checks seqno for replay protection
8. Wallet contract increments seqno
9. Wallet contract executes both transfers (to recipient and to service)

Key characteristics:

• Who signs: User
• Who sends: Service (internal message)
• Who pays gas: Service (in TON), gets compensated in Jettons

This pattern enables users to pay gas in Jettons instead of TON.

Example 3: Server-controlled operations

How it works:

1. User requests authorization from server
2. Server validates request and signs authorization message (includes validity period and operation parameters)
3. User sends server-signed message to contract (with payment)
4. Contract verifies server’s signature
5. Contract checks validity period
6. Contract performs authorized action (deploy, mint, claim)
7. If user tries to send same message again, contract ignores it (state already changed)

Key characteristics:

• Who signs: Server
• Who sends: User (internal message with payment)
• Who pays gas: User

This pattern is useful when backend needs to authorize specific operations (auctions, mints, claims) without managing private keys for each user.

Real-world example: telemint contract uses server-signed messages to authorize NFT deployments.

Message structure for signing

When designing a signed message, you choose how to organize the signed data — the message fields that will be hashed and verified. The key question: is the signed data a slice (part of a cell) or a cell (separate cell)? This affects gas consumption during signature verification.

Approach 1: Signed data as slice

After loading the signature from the message body, the signed data remains as a slice — a part of the cell that may contain additional data and references.

Used in: Wallet v1-v5

Schema — Wallet v3r2:

msg_body$_ signature:bits512 subwallet_id:uint32
           seqno:uint32 valid_until:uint32
           mode:uint8 message_to_send:^Cell
           = ExternalInMessage;

Verification in FunC:

slice signature = in_msg_body~load_bits(512);
slice signed_data = in_msg_body;  // Remaining data

int hash = slice_hash(signed_data);  // 526 gas
throw_unless(35, check_signature(hash, signature, public_key));

Gas analysis:

After loading the signature, the remaining data is a slice. To verify the signature, the contract needs to hash this slice. In TVM, the method for hashing a slice is slice_hash(), which costs 526 gas.

Why expensive?
slice_hash() internally rebuilds a cell from the slice, copying all data and references.

TVM v12+ optimization: In TVM version 12+, use builder_hash() instead. Convert the slice to a builder and hash it — this costs less than 100 gas total. See TVM v12 improvement below for details.

Approach 2: Signed data as cell

The signed data is stored in a separate cell, placed as a reference in the message body.

Used in: Preprocessed Wallet v2, Highload Wallet v3

Schema — Preprocessed Wallet v2:

_ valid_until:uint64 seqno:uint16 actions:^Cell = MsgInner;

msg_body$_ signature:bits512 msg_inner:^MsgInner = ExternalInMessage;

Verification in FunC:

slice signature = in_msg_body~load_bits(512);
cell signed_data = in_msg_body~load_ref();  // Signed data as cell

int hash = cell_hash(signed_data);  // 26 gas
throw_unless(35, check_signature(hash, signature, public_key));

Gas analysis:

The signed data is loaded as a cell from the reference. To get its hash, the contract uses cell_hash(), which costs only 26 gas.

Why efficient?
Every cell in TON stores its hash as metadata. cell_hash() reads this precomputed value directly — no rebuilding, no copying.

Trade-off:
This approach adds one extra cell to the message, slightly increasing the forward fee. However, the gas savings (~500 gas) outweigh the forward fee increase.

TVM v12 improvement

TVM version 12 introduced efficient builder hashing (HASHBU instruction), which makes signed data as slice approach much more gas-efficient.

Verification in FunC (TVM v12+):

slice signature = in_msg_body~load_bits(512);
slice signed_data = in_msg_body;

builder b = begin_cell().store_slice(signed_data);
int hash = b.builder_hash();
throw_unless(35, check_signature(hash, signature, public_key));

Gas comparison:

Method	Gas cost	Notes
slice_hash()	526 gas	Rebuilds cell from slice
Builder hashing (slice)	<100 gas	v12+: cheap, uses HASHBU
cell_hash() (cell)	26 gas	Uses precomputed cell hash

Conclusion:
In TVM v12+, both approaches are gas-efficient. New contracts can choose based on code simplicity and forward fee considerations.

Reference: GlobalVersions.md — TVM v12 updates

How to sign messages in TypeScript

Prerequisites

• Node.js 18+ or TypeScript environment
• @ton/core, @ton/crypto packages installed

Install required packages:

npm install @ton/core @ton/crypto

Step 1: Generate or load a mnemonic

A mnemonic is your wallet’s master secret. It derives the private key used to sign messages.

Generate a new mnemonic:

import { mnemonicNew } from '@ton/crypto';

const mnemonic = await mnemonicNew(24); // Array of 24 words

Load an existing mnemonic:

const mnemonic = 'word1 word2 word3 ... word24'.split(' ');

Protect your mnemonic: Anyone with access to your mnemonic can control your wallet and all funds. Store it securely (password manager, hardware wallet, encrypted storage). Never commit it to version control.

Step 2: Derive the keypair

Convert the mnemonic to an Ed25519 keypair:

import { mnemonicToPrivateKey } from '@ton/crypto';

const keyPair = await mnemonicToPrivateKey(mnemonic);
// keyPair.publicKey  — stored in contract
// keyPair.secretKey  — used to sign messages

Step 3: Build the signed data

Build the message data that will be signed:

import { beginCell } from '@ton/core';

// Build signed data (example: wallet message)
const seqno = 5;
const validUntil = Math.floor(Date.now() / 1000) + 60; // 60 seconds from now

const signedData = beginCell()
    .storeUint(seqno, 32)
    .storeUint(validUntil, 32)
    // ... other fields (subwallet_id, actions, etc.)
    .endCell();

Step 4: Create the signature

Sign the hash of the signed data:

import { sign } from '@ton/crypto';

const signature = sign(signedData.hash(), keyPair.secretKey);
// signature is a Buffer with 512 bits

Step 5: Build the message body

Choose the structure based on your contract (see Message structure for signing above):

// Approach 1: Signed data as slice
const messageBodyInline = beginCell()
    .storeBuffer(signature)             // 512 bits
    .storeSlice(signedData.asSlice())   // Signed data as slice
    .endCell();

// Approach 2: Signed data as cell
const messageBodySeparate = beginCell()
    .storeBuffer(signature)             // 512 bits
    .storeRef(signedData)               // Signed data as cell
    .endCell();