Contracts

Contracts in Tact are similar to classes in popular object-oriented languages, except that their instances are deployed on the blockchain and they can’t be passed around like Structs and Messages.

Self-references

Contracts and traits have a built-in identifier self, which is used to refer to their fields (persistent state variables and constants) and methods (internal functions):

contract Example {
    // persistent state variables
    foo: Int;

    init() {
        self.foo = 42; // <- referencing variable foo through self.
    }
}

contract ExampleParams(
    // persistent state variables
    foo: Int,
) {
    receive() {
        self.foo = 42; // <- referencing variable foo through self.
    }
}

Structure

Each contract can be defined with or contain:

• Inherited traits
• Supported interfaces
• Contract parameters
• Persistent state variables
• Constructor function init()
• Contract constants
• Getter functions
• Receiver functions
• Internal functions

Inherited traits, with

Contracts can inherit all declarations and definitions from traits and override some of their default behaviors. In addition to that, every contract and trait implicitly inherits the special BaseTrait trait.

To inherit a trait, specify its name after the keyword with in the contract’s declaration. To inherit multiple traits at once, specify their names in a comma-separated list with an optional trailing comma.

trait InheritMe {}
trait InheritMeToo {}

// A contract inheriting a single trait
contract Single with InheritMe {}

// A contract inheriting multiple traits
contract Plural with
    InheritMe,
    InheritMeToo, // trailing comma is allowed
{}

As traits are not allowed to have an init() function, a contract inheriting a trait with any persistent state variables declared must either provide its own init() function or declare contract parameters.

trait Supe { omelander: Bool }

// This contract will perform lazy initialization,
// setting its data on-chain after the initial deployment
contract LazyVot with Supe {
    init() { self.omelander = false }
}

// This contract will directly set its values with the
// initial data received from the deployment message
contract Vot(
    omelander: Bool,
) with Supe {}

If declared or defined in a trait, internal functions and constants can be marked as virtual or abstract and overridden in contracts inheriting from the trait.

Supported interfaces, @interface(…)

It’s hard to determine what a contract does and which receivers and getters it has without examining its source code. Sometimes the source is unavailable or inaccessible, leaving one to try to disassemble and introspect the contract, which is a very messy and error-prone approach with diminishing returns and no real reproducibility.

To resolve this issue, an OTP-001: Supported Interfaces was created. According to it, Tact contracts can report the list of supported interfaces through a special supported_interfaces getter. That getter is accessible off-chain using any TON Blockchain explorer — one simply needs to specify supported_interfaces as a method to execute and obtain a list of hexadecimal values.

These hexadecimal values are truncated to the first 128 bits of SHA-256 hashes of the original String values of the supported interfaces. The first value in this list must equal $\mathrm{0x5cec3d5d2cae7b1e84ec39d64a851b66}$ in hexadecimal notation, which is the first half of the SHA-256 hash for "org.ton.introspection.v0". If the first value is incorrect, you must stop trying to introspect the contract, as it does not conform to the Supported Interfaces proposal.

To declare support for a certain interface, add one or more @interface("…") attributes directly before contract and trait declarations:

@interface("His name is")
@interface("John")
contract SeeNah with Misc {
    // ...
}

@interface("name_of_your_org - miscellaneous")
trait Misc {
    // ...
}

Tact provides a small set of interfaces under specific conditions:

• "org.ton.abi.ipfs.v0", according to OTP-003: Self-ABI Reporting — opt-in via ipfsAbiGetter config property
• "org.ton.deploy.lazy.v0", according to OTP-005: Argument-addressable contracts
• "org.ton.debug.v0", but only if debug mode is enabled

Some traits in standard libraries define their interfaces as well:

• Ownable trait specifies "org.ton.ownable"
• OwnableTransferable trait specifies "org.ton.ownable.transferable.v2"
• Stoppable trait specifies "org.ton.stoppable"
• Resumable trait specifies "org.ton.resumable"

To enable the generation of the supported_interfaces getter and use the @interface() attribute in your Tact contracts, modify the tact.config.json file in the root of your project (or create it if it does not yet exist), and set the interfacesGetter property to true.

If you are working on a Blueprint-based project, you can enable supported_interfaces in the compilation configs of your contracts, which are located in a directory named wrappers/:

wrappers/YourContractName.compile.ts

import { CompilerConfig } from '@ton/blueprint';

export const compile: CompilerConfig = {
  lang: 'tact',
  target: 'contracts/your_contract_name.tact',
  options: {
    interfacesGetter: true, // ← that's the stuff!
  }
};

Additionally, tact.config.json may still be used in Blueprint projects. In such cases, values specified in tact.config.json act as defaults unless modified in the wrappers/.

Note

If you have the separateCompilables option set to true in the blueprint.config.ts, then the .compile.ts files will be located in the compilables/ directory, and not in wrappers/.

Caution

Be aware that adding an interface does not guarantee that the contract actually implements any particular functionality or that it implements it in any particular way. It is simply an off-chain, verifiable promise indicating that a contract might contain some specific code. It is your responsibility to trust, but verify, such claims.

In addition, there is no guarantee that there will not be name clashes between different interfaces, although they are unlikely because even the first 128 bits of SHA-256 provide sufficient collision resistance.

Contract parameters

Available since Tact 1.6

Most contracts do not require any on-chain deployment logic that runs just once after the contract’s deployment is completed. As such, the costly lazy deployment strategy provided by the init() function is generally discouraged in favor of simple, direct deployments with initial code and initial data.

To declare persistent state variables and set their values during such deployments, use the following contract parameters syntax:

contract ContractParameters(
    // persistent state variables declared via the contract parameters syntax
    val: Int,              // Int, implicitly serialized to a 257-bit signed
    val32: Int as uint32,  // Int, serialized to a 32-bit unsigned
    mapVal: map<Int, Int>, // Int keys to Int values
    optVal: Int?,          // Int or null
) {
    // ...
}

State variables declared in this way have no default value. Instead, they get their initial data only when the contract is deployed, which is much cheaper compared to deployments with an extra initialization step in the init() function.

The use of contract parameters syntax conflicts with using an init() function or declaring persistent state variables via the contract fields syntax. Whenever possible, prefer using contract parameters unless you need specific on-chain deployment logic that must be run exactly once, i.e. via the init() function.

contract ParamParamParam(
    param1: Int,
    param2: Int,
) {
    // COMPILATION ERROR! init() cannot be used along with contract parameters
    init(param1: Int, param2: Int) {}
}

An empty parameter list is still a parameter list, meaning that the contract won’t have an implicit or explicit init() function and will enjoy storage write optimizations. Removing the empty list makes a contract use the delayed initialization with an implicit init() function.

contract StillParam() {
    // COMPILATION ERROR! init() cannot be used along with contract parameters
    init() {}
}

contract LazyInit {
    // Everything's ok, and the following init() is redundant because there
    // would be an implicit empty init() anyway in the absence of contract parameters.
    init() {}
}

Note

To obtain the initial state of the target contract in internal functions, receivers, or getters, use the initOf expression.

To obtain only the contract’s code, use the codeOf expression.

Persistent state variables

Contracts can define state variables that persist between contract calls, thus commonly referred to as storage variables. Contracts in TON pay rent in proportion to the amount of persistent space they consume, so compact representations via serialization are encouraged.

The storage variables can be defined by using contract parameters or by using the following contract fields syntax:

contract ContractFields {
    // persistent state variables declared via the contract fields syntax
    val: Int;              // Int, implicitly serialized to a 257-bit signed
    val32: Int as uint32;  // Int, serialized to a 32-bit unsigned
    mapVal: map<Int, Int>; // Int keys to Int values
    optVal: Int?;          // Int or null
}

State variables defined via the contract fields syntax must have a default value or be initialized in the init() function, which runs once on deployment of the contract. The only exception is for persistent state variables of type map<K, V>, since they are initialized empty by default.

The default value of state variables is assigned before any values can be assigned in the init() function.

contract Example {
    // persistent state variables
    var1: Int = 0; // initialized with default value 0

    // constructor function
    init() {
        self.var1 = 42; // overrides the default to 42
    }
}

As the contract state is updated at the very end of the compute phase of the transaction, intermediate assignments of Int values exceeding the limits specified by serialization formats won’t fail immediately. Instead, such assignments would cause an exit code 5 only after all statements have been executed.

This is to be expected because the integers in the temporary TVM memory, which is used to process the compute phase, always have $257$ bits and are capable of holding values in the inclusive range from $-2^{256}$ to $2^{256} - 1$.

contract DeRanged {
    // Persistent state variables
    var: Int as uint8; // cannot store values outside the 0-255 range

    init() {
        self.var = -1;  // this won't fail immediately
        self.var = 500; // and this won't fail right away either

    } // only here, at the end of the compute phase,
      // would an error be thrown with exit code 5:
      // Integer out of expected range
}

In the end, this means that you cannot rely on intermediate out-of-bounds checks because there are none at TVM runtime, and only the last assignment of each state variable is used to update its persistent state value.

contract Zero {
    // Persistent state variables
    var: Int as uint8;  // cannot store values outside the 0-255 range
    var2: Int as uint4; // cannot store values outside the 0-15 range

    init() {
        self.var = -1; // this won't fail
        self.var = 0;  // this is in the range of `uint8`

        self.var2 = -1; // this won't fail
        self.var2 = 15; // this is in the range of `uint4`

    } // no errors, and now `self.var` is 0 and `self.var2` is 15
}

The above contract fields syntax for declaring persistent state variables conflicts with the use of contract parameters. Use one or the other, but not both.

contract ParamParamParam(
    param1: Int,
    param2: Int,
) {
    // COMPILATION ERROR! Cannot use contract fields along with contract parameters.
    field1: Int;
    field2: Int;
}

Note

Tact supports local, non-persistent state variables too. See: Variable declaration.

Contract constants

Unlike variables, constants cannot change. Their values are calculated at compile-time and cannot change during execution.

There isn’t much difference between constants defined outside of a contract (global constants) and those inside the contract (contract constants). Those defined outside can be used by other contracts in your project.

Constant initialization must be relatively simple and only rely on values known during compilation. If you add two numbers, for example, the compiler will calculate the result during the build and put the result in your compiled code.

You can read constants both in receivers and in getters.

Unlike contract variables, contract constants don’t consume space in persistent state. Their values are stored directly in the code Cell of the contract.

// global constants are calculated at compile-time and cannot change
const GlobalConst1: Int = 1000 + ton("42") + pow(10, 9);

contract Example {
    // contract constants are also calculated at compile-time and cannot change
    const ContractConst1: Int = 2000 + ton("43") + pow(10, 9);

    // contract constants can be an easy alternative to enums
    const StateUnpaid: Int = 0;
    const StatePaid: Int = 1;
    const StateDelivered: Int = 2;
    const StateDisputed: Int = 3;

    get fun sum(): Int {
        // access constants from anywhere
        return GlobalConst1 + self.ContractConst1 + self.StatePaid;
    }
}

Read more about constants on their dedicated page: Constants.

Constructor function init()

On deployment of the contract, the constructor function init() is run. Unlike contract parameters, it performs a delayed initialization of the contract data, setting the values of persistent state variables on-chain.

If a contract has any persistent state variables without default values specified, it must initialize them in this function.

contract Example {
    // persistent state variables
    var1: Int = 0; // initialized with default value 0
    var2: Int;     // must be initialized in the init() function
    var3: Int = 7; // initialized with default value 7

    // constructor function
    init() {
        self.var2 = 42;
        self.var3 = 32; // overrides the default to 32
    }
}

If a contract doesn’t have any persistent state variables, or if they all have their default values specified, it may omit the init() function declaration altogether. That is because unless explicitly declared, the empty init() function is present by default in all contracts that do not declare contract parameters.

The following is an example of a valid empty contract:

contract IamEmptyAndIKnowIt {}

For your convenience, the parameter list of init() can have a trailing comma:

contract TheySeeMeTrailing {
    init(
        param1: Int,
        param2: Int, // trailing comma is allowed
    ) {
        // ...
    }
}

Usage of the init() function conflicts with the use of contract parameters. Use one or the other, but not both.

contract ParamParamParam(
    param1: Int,
    param2: Int,
) {
    // COMPILATION ERROR! init() cannot be used along with contract parameters
    init(param1: Int, param2: Int) {}
}

Note that even an empty contract parameter list counts as using contract parameters syntax and means that the contract won’t have any variables in its persistent state. Removing the empty list makes a contract use the delayed initialization with an implicit init() function.

contract StillParam() {
    // COMPILATION ERROR! init() cannot be used along with contract parameters
    init() {}
}

contract LazyInit {
    // Everything's ok, and the following init() is redundant because there
    // would be an implicit empty init() anyway in the absence of contract parameters.
    init() {}
}

Note

To obtain the initial state of the target contract in internal functions, receivers, or getters, use the initOf expression.

To obtain only the contract’s code, use the codeOf expression.

Getter functions

Getter functions are not accessible from other contracts and are exported only to the off-chain world.

Additionally, getters cannot modify the contract’s state variables; they can only read their values and use them in expressions.

contract HelloWorld {
    foo: Int;

    init() {
        self.foo = 0;
    }

    // getter function with return type Int
    get fun foo(): Int {
        return self.foo; // can't change self.foo here
    }
}

Read more about them in their dedicated section: Getter functions

Receiver functions

Receiver functions in Tact can be one of the following three kinds:

• receive(), which receives internal messages (from other contracts).
• bounced(), which is called when an outgoing message from this contract bounces back.
• external(), which doesn’t have a sender and can be sent by anyone in the world.

message CanBounce {
    counter: Int;
}

contract HelloWorld {
    counter: Int;

    init() {
        self.counter = 0;
    }

    get fun counter(): Int {
        return self.counter;
    }

    // internal message receiver, which responds to a string message "increment"
    receive("increment") {
        self.counter += 1;

        // sending the message back to the sender
        send(SendParameters{
            to: sender(),
            value: 0,
            mode: SendRemainingValue | SendIgnoreErrors,
            body: CanBounce{counter: self.counter}.toCell(),
        });
    }

    // bounced message receiver, which is called when the message bounces back to this contract
    bounced(src: bounced<MsBounced>) {
        self.counter = 0; // reset the counter in case the message bounces
    }

    // external message receiver, which responds to off-chain message "hello, it's me"
    external("hello, it's me") {
        // can't be replied to as there's no sender!
        self.counter = 0;
    }
}

Naming a parameter of the receiver function with an underscore _ indicates that its value is unused and discarded. This is useful when you don’t need to inspect the received message and only want it to convey a specific opcode:

message(42) UniverseCalls {}

contract Example {
    receive(_: UniverseCalls) {
        // Got a Message with opcode 42
    }
}

Internal functions

These functions behave similarly to private methods in popular object-oriented languages — they’re internal to contracts and can be called by prefixing them with a special identifier self. That’s why internal functions are sometimes referred to as “contract methods.”

Internal functions can access the contract’s persistent state variables and constants.

They can only be called from receivers, getters, and other internal functions, but not from other contracts or init().

contract Functions {
    val: Int = 0;

    // this contract method can only be called from within this contract and access its variables
    fun onlyZeros() {
        require(self.val == 0, "Only zeros are permitted!");
    }

    // receiver function, which calls the internal function onlyZeros
    receive("only zeros") {
        self.onlyZeros();
    }
}

Note

Tact supports other kinds of functions too. See: Functions.