config

Module for configuring the emulated blockchain environment.

This module provides utilities for managing TON Blockchain configuration parameters. Configuration parameters control network behavior, including gas prices, storage costs, validator settings, and system contract addresses. These parameters are stored in the masterchain configuration and are used by the TON Virtual Machine to execute transactions.

For detailed information about each blockchain configuration parameter, see the TON Blockchain Configuration Reference in the TON documentation.

Examples:

// Set custom gas prices while running tests
var config = testing.getConfig();
val gasPrices = GasPrices {
    flatGasLimit: 0,
    flatGasPrice: 0,
    other: GasPricesExtended {
        gasPrice: 1000,
        gasLimit: 1_000_000,
        // ...
    },
};
config.setGasPrices(gasPrices, MASTERCHAIN);
testing.setConfig(config); // apply to emulated environment

// Access storage prices
val storagePrices = config.getStoragePrices();
println("Bit price: {}", storagePrices);

Definitions

BlockchainConfigMap

type BlockchainConfigMap = map<uint32, cell>

Type representing the blockchain configuration.

The configuration is a key-value map where keys are parameter indices (0-255) and values are cells containing the serialized configuration parameter data. Configuration parameters are defined in the block.tlb TL-B schema.

BlockchainConfigMap.set* methods mutate only this in-memory map. To apply updates to the emulator globally, call testing.setConfig with the mutated config. That apply step updates both the emulator world state and the current VM context's C7-visible config mirrors, so follow-up reads in the same test run see the committed values.

BlockchainConfigMap.setParamRaw

fun BlockchainConfigMap.setParamRaw(mutate self, index: uint32, data: cell): void

Sets a raw configuration parameter at the given index.

This is a low-level function that directly stores a cell at the specified parameter index. For type-safe parameter access, prefer using specialized setter functions such as BlockchainConfigMap.setGasPrices, BlockchainConfigMap.setStoragePrices, or BlockchainConfigMap.setGlobalVersion. This mutates only the local BlockchainConfigMap value until you call testing.setConfig.

Parameters:

• index: The configuration parameter index (typically 0-90)
• data: The serialized cell containing the parameter value

Example:

config.setParamRaw(20, gasCell);

BlockchainConfigMap.getParamRaw

fun BlockchainConfigMap.getParamRaw(self, index: uint32): cell

Retrieves a raw configuration parameter at the given index.

This is a low-level function that returns a cell containing the serialized configuration data. For type-safe parameter access, prefer using specialized getter functions such as BlockchainConfigMap.getGasPrices, BlockchainConfigMap.getStoragePrices, or BlockchainConfigMap.getGlobalVersion.

Parameters:

• index: The configuration parameter index (typically 0-90)

Returns: The raw cell containing the serialized parameter value.

Example:

val paramCell = config.getParamRaw(20);

GLOBAL_VERSION_INDEX

const GLOBAL_VERSION_INDEX = 8

Configuration parameter index for global network version (Param 8).

This parameter contains the network version number and capability flags supported by validators. It is used to coordinate network upgrades and enable/disable protocol features.

GlobalVersion

struct (0xc4) GlobalVersion {
    /// The current network version number.
    version: uint32
    /// Bitmask of supported capabilities. Each bit represents a specific network feature.
    capabilities: uint64
}

Network version and capabilities information (Param 8).

This struct contains the current network version and a set of capability flags that indicate which features are supported by the network.

BlockchainConfigMap.setGlobalVersion

fun BlockchainConfigMap.setGlobalVersion(mutate self, version: GlobalVersion): void

Sets the global network version and capabilities (Param 8).

This function updates the network version and validator capabilities configuration. When validators vote to update the network, they update this parameter, allowing the TON Blockchain to upgrade without downtime. This mutates only the local BlockchainConfigMap value until you call testing.setConfig.

Parameters:

• version: The new global network version struct containing version and capabilities

Example:

val newVersion = GlobalVersion {
    version: 5,
    capabilities: 0xFF
};
config.setGlobalVersion(newVersion);
if (!testing.setConfig(config)) {
    Assert.fail("Failed to apply config");
}

BlockchainConfigMap.getGlobalVersion

fun BlockchainConfigMap.getGlobalVersion(self): GlobalVersion

Retrieves the global network version and capabilities (Param 8).

This function reads the current network version and capabilities supported by validators. Use this to determine which network features are available.

Returns: GlobalVersion struct containing version number and capabilities bitmask.

Example:

val version = config.getGlobalVersion();
println("Network version: {}, capabilities: {}", version.version, version.capabilities);

STORAGE_PRICES_INDEX

const STORAGE_PRICES_INDEX = 18

Configuration parameter index for storage prices (Param 18).

Storage prices determine the cost of storing data on the TON Blockchain. These costs are used to prevent spam and ensure network maintenance is properly funded.

StoragePrices

struct (0xcc) StoragePrices {
    /// Unix timestamp indicating when these prices became effective.
    initialUnixTime: uint32
    /// Price per bit of storage in basechain workchains for 65536 seconds, in nanotons.
    bitPrice: uint64
    /// Price per cell of storage in basechain workchains for 65536 seconds, in nanotons.
    cellPrice: uint64
    /// Price per bit of storage in the masterchain for 65536 seconds, in nanotons.
    masterchainBitPrice: uint64
    /// Price per cell of storage in the masterchain for 65536 seconds, in nanotons.
    masterchainCellPrice: uint64
}

Storage price configuration for the TON Blockchain (Param 18).

This struct defines the pricing for data storage in both the masterchain and regular workchains. Prices are given per 65536 seconds of storage. Storage fees are calculated based on the number of bits and cells used to represent contract code and data.

StoragePricesDict

type StoragePricesDict = map<uint32, StoragePrices>

Dictionary mapping Unix timestamps to storage price configurations.

This allows different storage prices to apply at different periods in time. The dictionary is indexed by Unix timestamp values.

INITIAL_UNIXTIME_STORAGE_INDEX

const INITIAL_UNIXTIME_STORAGE_INDEX = 0

Configuration parameter index for the initial storage price (timestamp 0).

This index refers to the storage price entry at index 0, which represents the initial storage price configuration that applies from the beginning of time.

StoragePricesDict.getInitial

fun StoragePricesDict.getInitial(self): StoragePrices

Retrieves the initial storage price configuration from the dictionary.

Gets the storage price entry at index 0, which contains the initial pricing that applies from the beginning of time until the first timestamp-indexed price update.

Returns: StoragePrices configuration containing the initial storage price parameters.

Example:

val storagePrices = config.getStoragePrices();
val initialPrices = storagePrices.getInitial();
println("Initial bit price: {}", initialPrices.bitPrice);

StoragePricesDict.setInitial

fun StoragePricesDict.setInitial(mutate self, prices: StoragePrices): void

Sets the initial storage price configuration in the dictionary.

Updates the storage price entry at index 0 with new pricing parameters. This affects the base storage price that applies from the beginning of time.

Parameters:

• prices: The new StoragePrices configuration to set as the initial entry

Example:

var storagePrices = config.getStoragePrices();
val newInitialPrices = StoragePrices {
    initialUnixTime: 0,
    bitPrice: 1,
    cellPrice: 1000,
    masterchainBitPrice: 1,
    masterchainCellPrice: 1000
};
storagePrices.setInitial(newInitialPrices);
config.setStoragePrices(storagePrices);
if (!testing.setConfig(config)) {
    Assert.fail("Failed to apply config");
}

BlockchainConfigMap.setStoragePrices

fun BlockchainConfigMap.setStoragePrices(mutate self, prices: StoragePricesDict): void

Sets the storage price configuration (Param 18).

Storage prices are organized as a dictionary mapping timestamps to price structures, allowing for price adjustments over time. This function updates the entire storage price dictionary. This mutates only the local BlockchainConfigMap value until you call testing.setConfig.

Parameters:

• prices: A dictionary mapping Unix timestamps to StoragePrices configurations

Example:

var pricesDict = StoragePricesDict [];
pricesDict.set(1_000_000, StoragePrices {
    initialUnixTime: 1_000_000,
    bitPrice: 1,
    cellPrice: 1000,
    masterchainBitPrice: 1,
    masterchainCellPrice: 1000
});
config.setStoragePrices(pricesDict);
if (!testing.setConfig(config)) {
    Assert.fail("Failed to apply config");
}

BlockchainConfigMap.getStoragePrices

fun BlockchainConfigMap.getStoragePrices(self): StoragePricesDict

Retrieves the storage price configuration (Param 18).

Returns a dictionary of storage prices indexed by timestamp. Use this to determine the cost of storing data on the blockchain.

Returns: StoragePricesDict containing storage price configurations indexed by timestamp.

Example:

val storagePrices = config.getStoragePrices();
val prices = storagePrices.get(1_000_000);
println("Bit price: {}, Cell price: {}, Masterchain bit price: {}",
    prices.bitPrice, prices.cellPrice, prices.masterchainBitPrice);

GasPricesExtended

struct (0xde) GasPricesExtended {
    /// Price of 65536 gas units in nanotons.
    gasPrice: uint64
    /// Maximum amount of gas that can be consumed per regular transaction.
    gasLimit: uint64
    /// Maximum amount of gas that can be consumed per system contract transaction.
    specialGasLimit: uint64
    /// Gas credit provided to process external messages, in gas units.
    gasCredit: uint64
    /// Maximum amount of gas that can be consumed within a single block.
    blockGasLimit: uint64
    /// Accumulated storage fee limit (in nanotons) above which contracts are frozen.
    freezeDueLimit: uint64
    /// Accumulated storage fee limit (in nanotons) above which contracts are deleted.
    deleteDueLimit: uint64
}

Gas price configuration for extended gas schemes (Param 20/21 variant).

This variant includes a special gas limit for system contracts.

GasPrices

struct (0xd1) GasPrices {
    /// Initial gas amount provided at flat price before standard pricing applies.
    flatGasLimit: uint64
    /// Flat price applied to the initial [GasPrices.flatGasLimit] amount of gas.
    flatGasPrice: uint64
    /// Additional gas pricing configuration applied after the flat pricing.
    other: GasPricesExtended
}

Gas price configuration with flat pricing prefix.

This allows for two-tiered pricing where a flat fee and price are applied first, followed by the standard pricing structure.

MASTERCHAIN_GAS_PRICES_INDEX

const MASTERCHAIN_GAS_PRICES_INDEX = 20

Configuration parameter index for masterchain gas prices (Param 20).

BASECHAIN_GAS_PRICES_INDEX

const BASECHAIN_GAS_PRICES_INDEX = 21

Configuration parameter index for basechain gas prices (Param 21).

BlockchainConfigMap.setGasPrices

fun BlockchainConfigMap.setGasPrices(mutate self, prices: GasPrices, chainType: int): void

Sets gas price configuration for the masterchain or basechain (Param 20/21).

Gas prices define the computational cost of executing transactions and smart contracts on the TON Blockchain. The complexity of any computation is measured in gas units, and each gas unit has a price in nanotons.

Parameters:

• prices: Gas price configuration struct
• chainType: Chain type constant - either BASECHAIN for basechain prices (Param 21) or MASTERCHAIN for masterchain prices (Param 20)

This mutates only the local BlockchainConfigMap value until you call testing.setConfig.

BlockchainConfigMap.getGasPrices

fun BlockchainConfigMap.getGasPrices(self, chainType: int): GasPrices

Retrieves gas price configuration for the masterchain or basechain (Param 20/21).

Returns the gas price configuration that determines transaction execution costs.

Parameters:

• chainType: If equal to MASTERCHAIN, reads Param 20; any other value (including BASECHAIN) reads Param 21

Returns: GasPrices configuration union containing the gas pricing parameters.

Example:

val gasPrices = config.getGasPrices(BASECHAIN);
println("Gas limit basechain: {}", gasPrices);

MsgForwardPrices

struct (0xea) MsgForwardPrices {
    /// Base price for forwarding a message, independent of its size, in nanotons.
    lumpPrice: uint64
    /// Price per bit of the message being forwarded, in nanotons per bit.
    bitPrice: uint64
    /// Price per cell of the message being forwarded, in nanotons per cell.
    cellPrice: uint64
    /// Factor for calculating the cost of immediate hypercube routing (IHR).
    ihrPriceFactor: uint32
    /// Fraction of the remaining fee used for the first transition along the message route (in 1/65536ths).
    firstFrac: uint16
    /// Fraction of the remaining fee used for subsequent transitions along the message route (in 1/65536ths).
    nextFrac: uint16
}

Message forwarding price configuration (Param 24/25).

This struct defines the costs associated with forwarding messages between accounts and shards in the TON Blockchain. Message routing uses these prices to calculate fees for message delivery.

MASTERCHAIN_MSG_FORWARD_PRICES_INDEX

const MASTERCHAIN_MSG_FORWARD_PRICES_INDEX = 24

Configuration parameter index for masterchain message forwarding prices (Param 24).

BASECHAIN_MSG_FORWARD_PRICES_INDEX

const BASECHAIN_MSG_FORWARD_PRICES_INDEX = 25

Configuration parameter index for basechain message forwarding prices (Param 25).

BlockchainConfigMap.setMsgForwardPrices

fun BlockchainConfigMap.setMsgForwardPrices(
    mutate self,
    prices: MsgForwardPrices,
    chainType: int,
): void

Sets message forwarding price configuration for the masterchain or basechain (Param 24/25).

Message forwarding prices determine the cost of sending messages between accounts in the TON Blockchain. These prices are used by the message routing mechanism to calculate message forwarding fees.

Parameters:

• prices: Message forwarding price configuration
• chainType: If equal to MASTERCHAIN, uses Param 24; any other value (including BASECHAIN) uses Param 25

This mutates only the local BlockchainConfigMap value until you call testing.setConfig.

Example:

val msgPrices = MsgForwardPrices {
    lumpPrice: 1000,
    bitPrice: 1,
    cellPrice: 100,
    ihrPriceFactor: 3,
    firstFrac: 21845,
    nextFrac: 21845
};
config.setMsgForwardPrices(msgPrices, MASTERCHAIN);
if (!testing.setConfig(config)) {
    Assert.fail("Failed to apply config");
}

BlockchainConfigMap.getMsgForwardPrices

fun BlockchainConfigMap.getMsgForwardPrices(self, chainType: int): MsgForwardPrices

Retrieves message forwarding price configuration for the masterchain or basechain (Param 24/25).

Returns the message forwarding prices that determine message routing costs.

Parameters:

• chainType: If equal to MASTERCHAIN, reads Param 24; any other value (including BASECHAIN) reads Param 25

Returns: MsgForwardPrices configuration containing message forwarding price parameters.

Example:

val msgPrices = config.getMsgForwardPrices(BASECHAIN);
println("Lump price: {}, Bit price: {}, Cell price: {}",
    msgPrices.lumpPrice, msgPrices.bitPrice, msgPrices.cellPrice);

PRECOMPILED_CONTRACTS_CONFIG_INDEX

const PRECOMPILED_CONTRACTS_CONFIG_INDEX = 45

Configuration parameter index for precompiled contracts (Param 45).

Precompiled contracts are built-in smart contracts optimized for specific computations. They consume a fixed amount of gas regardless of input size, making them more efficient than general-purpose contracts for their specific functions.

PrecompiledSmartContract

struct (0xb0) PrecompiledSmartContract {
    /// Fixed gas consumption for executing this precompiled contract.
    gasUsage: uint64
}

Precompiled smart contract configuration.

Specifies the gas usage for a precompiled contract.

PrecompiledContractsConfig

struct (0xc0) PrecompiledContractsConfig {
    /// Dictionary mapping 256-bit contract addresses to their gas usage configurations.
    list: map<uint256, PrecompiledSmartContract>
}

Configuration for all precompiled contracts (Param 45).

Contains a dictionary mapping contract addresses to their gas usage specifications. Precompiled contracts are optimized implementations of common operations provided by the system.

PrecompiledContractsConfig.addContractGas

fun PrecompiledContractsConfig.addContractGas(
    mutate self,
    hash: uint256,
    gasForComputePhase: uint64,
): bool

Adds a precompiled contract gas entry if hash is not already present.

Returns true when a new entry is inserted. Returns false for duplicate hash values, and keeps the original gasUsage unchanged.

BlockchainConfigMap.setPrecompiledContractsConfig

fun BlockchainConfigMap.setPrecompiledContractsConfig(
    mutate self,
    precompiledConfig: PrecompiledContractsConfig,
): void

Sets the precompiled contracts configuration (Param 45).

Updates the list of precompiled smart contracts and their associated gas costs. Precompiled contracts are system-provided optimizations for common cryptographic and utility operations. This mutates only the local BlockchainConfigMap value until you call testing.setConfig.

Parameters:

• precompiledConfig: Configuration containing the dictionary of precompiled contracts

Example:

var contractsList = map<uint256, PrecompiledSmartContract> [];
contractsList.set(0x123456, PrecompiledSmartContract { gasUsage: 1000 });
val precompiledConfig = PrecompiledContractsConfig {
    list: contractsList
};
config.setPrecompiledContractsConfig(precompiledConfig);
if (!testing.setConfig(config)) {
    Assert.fail("Failed to apply config");
}

BlockchainConfigMap.getPrecompiledContractsConfig

fun BlockchainConfigMap.getPrecompiledContractsConfig(self): PrecompiledContractsConfig

Retrieves the precompiled contracts configuration (Param 45).

Returns the configuration of all precompiled contracts available in the network, including their fixed gas costs. In the default emulator config this dictionary starts with one built-in entry. If you explicitly write an empty dictionary via BlockchainConfigMap.setPrecompiledContractsConfig and apply it with testing.setConfig, subsequent reads return an empty dictionary.

Returns: PrecompiledContractsConfig containing the precompiled contracts dictionary.

Example:

val precompiledConfig = config.getPrecompiledContractsConfig();
val contractsList = precompiledConfig.list;