Common

List of a basic functions that are available in all smart contracts.

sender

fun sender(): Address;

Returns the Address of the sender of the current message.

Usage example:

receive() {
  let whoSentMeMessage: Address = sender();
}

⚠️

Behaviour is undefined for getter functions, as they cannot have a sender nor they can send messages.

💡

In order to reduce gas usage, prefer using this function over calling context().sender when you only need to know the sender of the message.

require

fun require(condition: Bool, error: String);

Checks the condition and throws an exception with error message if the condition is false. Does nothing otherwise.

Usage example:

// now() has to return a value greater than 1000, otherwise an error message will be thrown
require(now() > 1000, "We're in the first 1000 seconds of 1 January 1970!");

now

fun now(): Int

Returns the current Unix time (opens in a new tab).

Usage example:

let timeOffset: Int = now() + 1000; // thousand seconds from now()

myBalance

fun myBalance(): Int;

Returns the remaining balance of the smart contract as an integer value in nanoToncoins, where nanoToncoin is the $\frac{1}{10^{9}}\mathrm{th}$ of the Toncoin.

Usage example:

let iNeedADolla: Int = myBalance();

⚠️

Note, that send() function does not update the contract's balance.

myAddress

fun myAddress(): Address;

Returns the address of the current smart contract as an Address.

Usage example:

let meMyselfAndI: Address = myAddress();

newAddress

fun newAddress(chain: Int, hash: Int): Address;

Creates a new Address based on the chain id (opens in a new tab) and the SHA-256 encoded hash value (opens in a new tab).

Usage example:

let oldTonFoundationAddr: Address =
    newAddress(0, 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);
    //         ↑  ------------------------------------------------------------------
    //         |  ↑
    //         |  sha-256 hash of contract's init package (StateInit)
    //         chain id: 0 is a workchain, -1 is a masterchain

⚠️

This method throws an error with exit code 136 if chain is invalid or with exit code 137 if chain points to the masterchain ( $-1$ ) without masterchain support enabled.

💡

Useful links:
chain (Workchain ID) in TON Docs (opens in a new tab)
hash (Account ID) in TON Docs (opens in a new tab)
Contract's init package (StateInit)

contractAddress

fun contractAddress(s: StateInit): Address;

Computes smart contract's Address in a workchain $0$ based on its StateInit.

Usage example:

let foundMeSome: Address = contractAddress(initOf SomeContract());

contractAddressExt

fun contractAddressExt(chain: Int, code: Cell, data: Cell): Address;

Computes smart contract's Address based on the chain id, contract's code and contract's initial state data. Use initOf expression to obtain initial code and initial data of a given contract.

Usage example:

let initPkg: StateInit = initOf SomeContract();
let hereBeDragons: Address = contractAddressExt(0, initPkg.code, initPkg.data);

⚠️

This method throws an error with exit code 136 if chain is invalid or with exit code 137 if chain points to the masterchain ( $-1$ ) without masterchain support enabled.

address

fun address(s: String): Address;

A compile-time function that converts a String with an address into the Address type.

Usage example:

contract Example {
    // Persistent state variables
    addr: Address =
        address("EQCD39VS5jcptHL8vMjEXrzGaRcCVYto7HUn4bpAOg8xqB2N"); // works at compile-time!
}

emit

fun emit(body: Cell);

Sends a message body to the outer world with the purpose of logging and analyzing it later off-chain. The message does not have a recipient and is gas-efficient compared to alternatives.

Usage example:

emit("Catch me if you can".asComment()); // asComment() converts a String to a Cell

cell

fun cell(bocBase64: String): Cell;

A compile-time function that embeds a base64-encoded BoC (opens in a new tab) bocBase64 as a Cell into the contract.

Usage example:

// Init package for Wallet V3R1 as a base64-encoded BoC:
cell("te6cckEBAQEAYgAAwP8AIN0gggFMl7qXMO1E0NcLH+Ck8mCDCNcYINMf0x/TH/gjE7vyY+1E0NMf0x/T/9FRMrryoVFEuvKiBPkBVBBV+RDyo/gAkyDXSpbTB9QC+wDo0QGkyMsfyx/L/8ntVD++buA=");

💡

Useful links:
Bag of Cells in TON Docs (opens in a new tab)

ton

fun ton(value: String): Int;

A compile-time function that converts the given Toncoins value from a human-readable format String to the nanoToncoins Int format.

Usage example:

ton("1");           // 10^9 nanoToncoins, which is equal to one Toncoin
ton("0.1");         // 10^8 nanoToncoins, which is equal to 0.1 Toncoin
ton("0.000000001"); // 1 nanoToncoin, which is equal to 10^-9 Toncoins

dump

fun dump(arg);

Prints the argument arg to the contract's debug console. Evaluated only if debug option is set in the configuration file, otherwise does nothing.

Can be applied to the following list of types and values:

Int
Bool
Builder, Cell or Slice
String or StringBuilder
map<k, v>
Optionals and null value
void, which is implicitly returned when a function doesn't have return value defined

Usage examples:

// Int
dump(42);
 
// Bool
dump(true);
dump(false);
 
// Builder, Cell or Slice
dump(beginCell());           // Builder
dump(emptyCell());           // Cell
dump(emptyCell().asSlice()); // Slice
 
// String or StringBuilder
dump("Hello, my name is..."); // String
dump(beginTailString());      // StringBuilder
 
// Maps
let m: map<Int, Int> = emptyMap();
m.set(2 + 2, 4);
dump(m);
 
// Special values
dump(null);
dump(emit("msg".asComment())); // As emit() function doesn't return a value, dump() would print #DEBUG#: void.

💡

For this function to work, the compiler option debug has to be set to true for the current project in the configuration file. Read more about debugging on the dedicated page: Debugging.

context

fun context(): Context;

Returns Context Struct, that consists of:

Field	Type	Description
bounced	`Bool`	Bounced (opens in a new tab) flag of the incoming message.
sender	`Address`	Internal address of the sender on the TON blockchain.
value	`Int`	Amount of nanoToncoins in a message.
raw	`Slice`	The reminder of the message as a `Slice`.

Usage example:

let ctx: Context = context();
require(ctx.value != 68 + 1, "Invalid amount of nanoToncoins, bye!");

💡

Note, that if you only need to know who sent the message, use the sender() function, as it's less gas-expensive.

Overview Strings