Invalid type passed!
Received:
{type}
Expected one of:
{asideVariants.join(", ")}
: <>
{title &&
{title}
}
{children}
}
;
};
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()`](/tolk/features/standard-library#random-uint256), but their results can be predicted by validators unless additional techniques are used.
## Why on-chain randomness is challenging
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:
1. Generate different seeds when creating blocks.
2. 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](#single-block-randomness) | [Block skipping](#multi-block-randomness-via-block-skipping) | [Commit-reveal](#external-randomness-via-the-commit-reveal-scheme) |
| ------------------------------------ | ---------------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------ |
| 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()`](/tolk/features/standard-library#random-initialize) function mixes the transaction's logical time into the current random seed. This provides basic entropy from blockchain state.
### How it works
Call `random.initialize()` once before using [`random.uint256()`](/tolk/features/standard-library#random-uint256) or [`random.range()`](/tolk/features/standard-library#random-range-limit) functions. The logical time adds variability to the seed, making it harder for observers to predict the outcome without executing the transaction.
```tolk title="Tolk" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
random.initialize();
// Generates values from 0 to 99
val 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
1. **Commit phase**: Each participant generates a secret off-chain and submits a domain-separated hash that binds the secret to the participant, contract, and round identifier.
2. **Reveal phase**: After all commitments are received, participants disclose their original secrets.
3. **Combination**: The contract verifies each reveal against its commitment, rejects duplicates or mismatches, builds a deterministic transcript (e.g., sorted by participant address or commit order), and hashes that transcript 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. Because external messages do not transfer funds, an attacker can resubmit them for free until the random outcome is favorable - so `random.initialize()` does not protect external entry points.
* 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](/ecosystem/nodes/cpp/mytonctrl/collator)) creating that block. The [validator node code](https://github.com/ton-blockchain/ton/blob/f59c363ab942a5ddcacd670c97c6fbd023007799/validator/impl/collator.cpp#L1590) generates 32 random bytes using cryptographically secure primitives:
```cpp title="C++" theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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](https://github.com/ton-blockchain/ton/blob/f59c363ab942a5ddcacd670c97c6fbd023007799/crypto/block/transaction.cpp#L876) to produce a per-contract seed:
```text theme={"theme":{"light":"github-light-default","dark":"dark-plus"},"languages":{"custom":["/resources/grammars/tolk.tmLanguage.json","/resources/grammars/tlb.tmLanguage.json","/resources/grammars/fift.tmLanguage.json","/resources/grammars/tasm.tmLanguage.json","/resources/grammars/func.tmLanguage.json"]}}
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.
### Random number generation
The [`RANDU256`](/tvm/instructions#f810-randu256) TVM instruction implements the actual random number generation.
1. Take the current seed `r` (32 bytes).
2. Compute a hash with `SHA512(r)`.
3. Use the first 32 bytes as the new seed.
4. Return the remaining 32 bytes as the random number.
Subsequent calls continue this chain, producing a deterministic sequence from the initial seed.