scripts

Module for public API to be used in scripts (interacting with real blockchain).

You write scripts to deploy and manage your contracts in a real blockchain. Use methods scripts.xxx in combination with net.xxx in scripts/some-file.tolk.

Writing scripts that operate testnet/mainnet differs from writing tests. In scripts, you connect your real wallet to send transactions. In scripts, you are not able to set blockchain config or create an unlimited treasury. In scripts, you wait for network responses, which takes time.

Any script can be run in either in emulation mode (without --net) or in a real blockchain (with --net).

Definitions

scripts

struct scripts

Root module for public API to be used in scripts along with net.xxx methods.

ActonWallet

struct ActonWallet {
    address: address
}

ActonWallet is a wallet created or registered by acton wallet CLI command. Use scripts.wallet("name") to "connect" a wallet by name. Available wallets are stored in Acton.toml either project-wise (local) or system-wise (global).

ActonWallet.toKeyPair

fun ActonWallet.toKeyPair(self): KeyPair

Returns the key pair for a wallet configured in wallets.toml or global.wallets.toml.

The privateKey field is the 32-byte Ed25519 seed used by crypto.sign and crypto.rawSign. This is available only for wallets opened by scripts.wallet when the script was started with --net.

ActonWallet.privateKey

fun ActonWallet.privateKey(self): int

Returns the wallet private key as a 32-byte Ed25519 seed.

ActonWallet.publicKey

fun ActonWallet.publicKey(self): int

Returns the wallet public key.

ActonWallet.walletId

fun ActonWallet.walletId(self): int

Returns the wallet id used by the opened wallet contract.

For wallet v5 this is the wallet_id stored in wallet data and used for signed requests.

ActonWallet.sign

fun ActonWallet.sign(self, data: cell): slice

Hashes and signs a cell with the wallet private key.

ActonWallet.rawSign

fun ActonWallet.rawSign(self, data: int): slice

Signs an already computed 256-bit hash with the wallet private key.

scripts.wallet

fun scripts.wallet(name: string): ActonWallet

Creates a new wallet for use in scripts. Unlike testing.treasury, the wallet can refer to a real wallet described in Acton.toml, and therefore can be used in scripts launched with --net to execute transactions on the real blockchain.

Without --net, the wallet refers to an internal wallet, created in the same way as in testing.treasury.

Note: in tests, use testing.treasury.

Example:

/// Script that deploys a counter contract using a wallet to real blockchain.
fun main() {
    val deployer = scripts.wallet("deployer");
    val counter = Counter.fromStorage({
        id: 8,
        counter: 0,
    });

    val result = counter.deploy(deployer.address, ton("0.05"));
    result.waitForFirstTransaction();

    println("Deployed counter to {}", counter.address);
}

scripts.fetchAccountState

fun scripts.fetchAccountState(addr: address): TlbAccountInfo?

Returns current account state for address or null if no information available or contract is not deployed.

The account state includes balance, storage information, and other account data. See TlbAccountInfo type for more information.

Example:

val state = scripts.fetchAccountState(contract.address);
if (state != null) {
    println("Balance: {:ton}", state.storage.balance.grams);
} else {
    println("Account not found");
}

scripts.fetchAccountStorageFee

fun scripts.fetchAccountStorageFee(addr: address, seconds: int): coins?

Returns storage fee for address for specified amount of seconds.

Returns null if the contract with given address is not deployed.

Example:

val storageFee = scripts.fetchAccountStorageFee(contract.address, 86400); // 1 day
if (storageFee != null) {
    println("Daily storage fee: {:ton}", storageFee);
}

scripts.fetchAccountBalance

fun scripts.fetchAccountBalance(of: address): coins

Get the balance of an address.

Returns 0 if the address is not deployed.

Example:

val balance = scripts.fetchAccountBalance(address);
println("{:ton}", balance);

scripts.fetchShardAccount

fun scripts.fetchShardAccount(addr: address): TlbShardAccount?

Returns the shard account state for an address.

The returned shard account can represent an uninitialized account.

Example:

val shard = scripts.fetchShardAccount(addr);
if (shard != null) {
    println("Last LT: {}", shard.lastTransLt);
}

scripts.fetchConfig

fun scripts.fetchConfig(): BlockchainConfigMap

Retrieves the current blockchain configuration.

Returns a map of all blockchain configuration parameters indexed from 0-90. The configuration includes gas prices, storage costs, validator settings, and other network parameters. Use specialized getter functions like BlockchainConfigMap.getGasPrices, BlockchainConfigMap.getStoragePrices, or BlockchainConfigMap.getGlobalVersion to access specific parameters.

For detailed information about blockchain configuration parameters, see the TON Blockchain Configuration Reference.

Returns: A BlockchainConfigMap containing all current blockchain configuration parameters.

Example:

val config = scripts.fetchConfig();

// Access specific configuration
val gasPrice = config.getGasPrices(BASECHAIN);
val storagePrices = config.getStoragePrices();
val globalVersion = config.getGlobalVersion();

println("Network version: {}", globalVersion.version);

scripts.isContractDeployed

fun scripts.isContractDeployed(addr: address): bool

Check if a contract with a specified address is deployed.

Returns true if the contract is deployed, false otherwise.

Example:

fun JettonWallet.getJettonBalance(self): coins {
    if (!scripts.isContractDeployed(self.address)) {
        return 0;
    }

    // if deployed, actually run get method
    val result = net.runGetMethod<JettonWalletDataReply>(self.address, "get_wallet_data");
    return result.jettonBalance;
}