Random number generation

Generating random numbers is a common smart contract task for applications such as gaming, trait generation for non-fungible tokens (NFTs), and decentralized lotteries. TON provides built-in functions like random.uint256(), but their results can be predicted by validators unless additional techniques are used.

Why on-chain randomness is challenging

Deterministic programs use pseudorandom number generators (PRNGs) to produce sequences that appear random but are actually deterministic, based on an initial seed value. Running the same program with the same seed will always produce the same sequence of numbers. If true randomness is required, the seed must come from an external entropy source that cannot be predicted or manipulated by adversaries. Smart contracts on TON use pseudorandom number generators (PRNGs) seeded with values derived from the blockchain state, such as block seeds generated by validators. While this prevents regular users from predicting random values before block production, validators themselves can influence randomness in two ways:

Generate different seeds when creating blocks.
Choose which blocks to include external messages in.

This limitation means all approaches to on-chain randomness involve trade-offs between speed, security, and decentralization guarantees.

Comparison of approaches

Factor	Single-block	Block skipping	Commit-reveal
Speed	Fast	Slow	Very slow
Implementation complexity	Low	Medium	High
Resistance to user manipulation	High	High	High
Resistance to validator manipulation	Low	Medium	High
Cost (gas + storage)	Low	Medium	High

Single-block randomness

The random.initialize() function initializes the random number generator with a seed derived from the transaction’s logical time. This provides basic entropy from blockchain state.

How it works

Call random.initialize() once before using random.uint256() or random.range() functions. The logical time adds variability to the seed, making it harder for observers to predict the outcome without executing the transaction.

Tolk

random.initialize();
// Generates values from 0 to 99
var randomNumber = random.range(100);

Security model

The single-block approach prevents attacks from regular users who cannot predict logical time. However, it is vulnerable to colluding validators who can generate seeds or choose message inclusion blocks.

Speed

The single-block approach is fast, as it executes inside a single transaction.

Use cases

Non-critical applications like gaming or cosmetic features.
NFT trait randomization.
Scenarios where validator trust is assumed.

Multi-block randomness via block skipping

Instead of using randomness from the current block, the contract waits for several blocks to pass before using their entropy. This approach sends messages across multiple blocks, making it harder for a single validator to control the final outcome.

How it works

The contract initiates an operation, then waits for responses that arrive several blocks later. The random seed from future blocks, which the initiating validator does not control, determines the result.

Security model

Block skipping is resistant to attacks from regular users and more resistant to single validators than single-block randomness. However, it is still vulnerable to a determined validator who represents a significant portion of the network, as they can still choose optimal timing to influence outcomes in blocks they generate.

Speed

Block skipping is significantly slower than single-block randomness, as it requires waiting for multiple blocks to be produced and finalized.

Use cases

Medium-stakes applications like lottery systems with moderate value.
Scenarios requiring better security than single-block randomness.

External randomness via the commit-reveal scheme

Multiple participants commit to secret values by publishing hashes, then reveal those values in a later phase. The final randomness is derived from combining all revealed values, ensuring no single party can determine the outcome alone. When properly implemented, this approach provides cryptographically secure randomness suitable for high-value applications.

How it works

Commit phase: Each participant generates a random number off-chain and submits its hash to the contract.
Reveal phase: After all commitments are received, participants disclose their original numbers.
Combination: The contract combines the revealed numbers (e.g., by XOR or sum) to produce the final random value.

Security model

The commit-reveal scheme is the most secure on-chain randomness approach, as it relies on cryptographic commitments and multiple independent participants. It prevents any single participant from unilaterally determining the final value. Validators can still influence timing or censor messages, but they cannot determine the final random value without colluding with participants. Commit-reveal schemes require careful incentive design. Participants may refuse to reveal if the outcome is unfavorable. Use penalties or collateral to enforce honest behavior.

Speed

The commit-reveal scheme is very slow compared to other approaches, as it involves multiple phases and requires waiting for several blocks to complete the process. The time to finality can range from minutes to hours depending on the number of participants and block times.

Implementation requirements

On-chain verification of commitments.
Penalty mechanisms for non-reveals or invalid reveals.
Timeout handling for missing participants.

Use cases

High-value applications like lotteries or auctions with significant funds at stake.
Decentralized gaming with financial stakes.
Systems requiring Byzantine fault tolerance.

Best practices

Always call random.initialize() before using random.uint256() or random.range() this prevents users from predicting values but does not protect against validators who control the block seed.
Keep randomness out of external message receivers. External messages remain vulnerable even with random.initialize().
Use hybrid or off-chain entropy for critical applications. Combine on-chain randomness with off-chain entropy, like external randomness oracles, when significant value is at risk.
Test randomness behavior across different blocks on testnet. Verify that contracts behave correctly when randomness is manipulated within validator capabilities.

How block random seeds work

Understanding the underlying mechanism helps evaluate security trade-offs.

Seed generation by validators

Each block’s random seed is generated by the validator (or collator) creating that block. The validator node code generates 32 random bytes using cryptographically secure primitives:

C++

prng::rand_gen().strong_rand_bytes(rand_seed->data(), 32);

A single validator generates this seed when creating a block, giving them control over the seed value. This is why single-block randomness is vulnerable to validator manipulation.

Per-contract randomization

The block seed is not used directly in contracts. Instead, it is hashed with the contract address to produce a per-contract seed:

contract_seed = SHA256(block_seed || contract_address)

This ensures each contract in the same block receives its own random seed, preventing cross-contract randomness correlation.