Addresses

Address represents a standard smart contract address on TON Blockchain.

See also: myAddress() function in the context and state reference.

newAddress

Gas-expensive

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

Creates a new Address based on the chain ID and the SHA-256 encoded hash value (account ID).

This function tries to resolve constant values at compile-time whenever possible.

Attempts to specify an invalid chain ID (not -1 or 0) detectable at compile-time will result in a compilation error.

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

Caution

Make sure you specify only supported workchain IDs: 0 for the basechain and -1 for the masterchain.

Useful links:

chain (Workchain ID) in TON Docs
hash (Account ID) in TON Docs
Contract’s init package (StateInit)

contractAddress

Gas-expensive

fun contractAddress(s: StateInit): Address;

Computes the smart contract’s Address in the workchain ID 0 (basechain) using the StateInit s of the contract. An alias to contractAddressExt(0, s.code, s.data).

Usage example:

let s: StateInit = initOf SomeContract();
let foundMeSome: Address = contractAddress(s);
let andSomeMore: Address = contractAddressExt(0, s.code, s.data);

foundMeSome == andSomeMore; // true

contractAddressExt

Gas-expensive

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

Computes the smart contract’s Address in the given chain ID using the contract’s code and its initial state data. Use the initOf expression to obtain the initial code and initial data of a given contract.

This function tries to resolve constant values at compile-time whenever possible.

Attempts to specify an invalid chain ID (not -1 or 0) that can be detected at compile-time will result in a compilation error.

Usage example:

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

contractHash

Available since Tact 1.6

fun contractHash(code: Cell, data: Cell): Int;

Computes and returns an Int value of the SHA-256 hash of the code and data of the given contract. To assemble the code and data cells together for hashing, the standard Cell representation is used.

This hash is commonly called the account ID. Together with the workchain ID, it deterministically forms the address of the contract on TON Blockchain.

Usage example:

let initPkg: StateInit = initOf SomeContract();
let accountId: Int = contractHash(initPkg.code, initPkg.data);
let basechainAddr: Address = newAddress(0, accountId);
let basechainAddr2: Address = contractAddressExt(0, initPkg.code, initPkg.data);

basechainAddr == basechainAddr2; // true

Useful links:

chain (Workchain ID) in TON Docs
hash (Account ID) in TON Docs
Contract’s init package (StateInit)
Standard Cell representation

forceBasechain

Available since Tact 1.6.3

fun forceBasechain(address: Address);

Checks whether the address is in the basechain, i.e., its chain ID is 0. If it is not, throws an exception with exit code 138: Not a basechain address.

Usage examples:

let someBasechainAddress: Address =
    newAddress(0, 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);

let someMasterchainAddress: Address =
    newAddress(-1, 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);

// Does not throw because the chain ID is 0
forceBasechain(someBasechainAddress);

try {
    // Throws because the chain ID is -1 (masterchain)
    forceBasechain(someMasterchainAddress);
} catch (exitCode) {
    // exitCode is 138
}

forceWorkchain

Available since Tact 1.6.4

fun forceWorkchain(address: Address, workchain: Int, errorCode: Int);

Parameterized version of forceBasechain().

Checks whether the address is in the workchain, i.e., its chain ID is equal to workchain. If it is not, throws an exception with exit code errorCode.

Usage examples:

let someBasechainAddress: Address =
    newAddress(0, 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);

let someMasterchainAddress: Address =
    newAddress(-1, 0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);

// Does not throw because the chain ID matches workchain parameter
forceWorkchain(someBasechainAddress, 0, 593);
forceWorkchain(someMasterchainAddress, -1, 593);

try {
    // Throws because the chain ID is 0 which doesn't match the workchain parameter, -1
    forceWorkchain(someBasechainAddress, -1, 593);
} catch (exitCode) {
    // exitCode is 593
}

parseStdAddress

Available since Tact 1.5

fun parseStdAddress(slice: Slice): StdAddress;

Converts a slice containing an address into the StdAddress struct and returns it.

The StdAddress is a built-in struct that consists of:

Field	Type	Description
workchain	Int as int8	Workchain ID of the address, usually $0$ (basechain) or $-1$ (masterchain)
address	Int as uint256	Address in the specified workchain

Attempts to pass a Slice with a layout different from the StdAddress or to load more data than the given Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let addr = address("EQDtFpEwcFAEcRe5mLVh2N6C0x-_hJEM7W61_JLnSF74p4q2");
let parsedAddr = parseStdAddress(addr.asSlice());

parsedAddr.workchain; // 0
parsedAddr.address;   // 107...lots of digits...287

// Using newAddress() function with the contents of StdAddress will yield the initial Address:
let addr2: Address = newAddress(parsedAddr.workchain, parsedAddr.address);
addr2 == addr; // true

Note

For parsing addresses of variable length, see the parseVarAddress() function.

parseVarAddress

Available since Tact 1.5

fun parseVarAddress(slice: Slice): VarAddress;

Converts a slice containing an address of variable length into the VarAddress struct and returns it.

The VarAddress is a built-in struct consisting of:

Field	Type	Description
workchain	Int as int32	Workchain ID of the variable-length address
address	Slice	Address in the specified workchain

Attempts to pass a Slice with a layout different from the VarAddress or to load more data than the given Slice contains throw an exception with exit code 9: Cell underflow.

Usage example:

let varAddrSlice = beginCell()
    .storeUint(6, 3)     // to recognize the following as a VarAddress
    .storeUint(123, 9)   // make address occupy 123 bits
    .storeUint(234, 32)  // specify workchain ID of 234
    .storeUint(345, 123) // specify address of 345
    .asSlice();
let parsedVarAddr = parseVarAddress(varAddrSlice);

parsedVarAddr.workchain;             // 234
parsedVarAddr.address;               // CS{Cell{002...2b3} bits: 44..167; refs: 0..0}
parsedVarAddr.address.loadUint(123); // 345

Caution

Variable-length addresses are intended for future extensions, and while validators must be ready to accept them in inbound messages, the standard (non-variable) addresses are used whenever possible.

StateInit.hasSameBasechainAddress

Available since Tact 1.6.1

extends fun hasSameBasechainAddress(self: StateInit, sender: Address): Bool;

Extension function for the StateInit struct.

Efficiently compares whether the given address matches the basechain address of the contract. Returns true if the addresses are the same; false otherwise.

fun example() {
    let init = initOf SomeContract();
    init.hasSameBasechainAddress(sender()); // returns true if sender matches contract's basechain address
}

This function provides a gas-optimized implementation compared to direct address comparison:

fun example() {
    let init = initOf SomeContract();
    sender() == contractAddress(sender()); // less efficient approach
}

Note

This function works only for basechain addresses!

Address.asSlice

extends fun asSlice(self: Address): Slice;

Extension function for the Address type.

Casts the Address back to the underlying Slice and returns it. The inverse of Slice.asAddressUnsafe().

Usage example:

let a: Address = myAddress();
let fizz: Slice = beginCell().storeAddress(a).asSlice();
let buzz: Slice = a.asSlice(); // cheap, unlike the previous statement

fizz == buzz; // true

Address.toString

Gas-expensive

extends fun toString(self: Address): String;

Extension function for the Address type.

Returns a String from an Address.

Usage example:

let community: Address = address("UQDpXLZKrkHsOuE_C1aS69C697wE568vTnqSeRfBXZfvmVOo");
let fizz: String = community.toString();

BasechainAddress

Available since Tact 1.6

struct BasechainAddress {
    hash: Int?;
}

Struct representing a basechain address.

A basechain address (workchain $0$) can be either empty (null hash) or contain a 256-bit hash value.

emptyBasechainAddress

Available since Tact 1.6

inline fun emptyBasechainAddress(): BasechainAddress;

Creates and returns an empty basechain address with a null hash.

When serialized, an empty basechain address is represented as addr_none.

Usage example:

fun example() {
    let emptyAddr: BasechainAddress = emptyBasechainAddress();
    emptyAddr.hash == null; // true
}

newBasechainAddress

Available since Tact 1.6

inline fun newBasechainAddress(hash: Int): BasechainAddress;

Creates and returns a new basechain address with the specified hash value.

Usage example:

fun example() {
    let addr: BasechainAddress = newBasechainAddress(0x83dfd552e63729b472fcbcc8c45ebcc6691702558b68ec7527e1ba403a0f31a8);
}

contractBasechainAddress

Available since Tact 1.6

inline fun contractBasechainAddress(s: StateInit): BasechainAddress;

Creates and returns a basechain address derived from a contract’s StateInit (code and data).

Usage example:

fun example() {
    let code: Cell = loadCell(); // load contract code
    let data: Cell = loadCell(); // load contract data
    let state: StateInit = StateInit { code, data };
    let addr: BasechainAddress = contractBasechainAddress(state);
}