Addresses

Address represents a standard smart contract address on TON Blockchain.

See also:

• myAddress() function in the context and state reference.
• Address-oriented extension functions for Builder and Slice types on their reference page: Cells, Builders and Slices.

newAddress

500+ gas

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 uncommon 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

500+ gas

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

500+ gas

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 lets you specify arbitrary chain IDs, including the common -1 (masterchain) and 0 (basechain) ones.

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 that cannot be parsed as a 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

Deprecated since Tact 1.6.8

fun parseVarAddress(slice: Slice): VarAddress;

This function has been deprecated since Tact 1.6.8. Any usages of this function will be reported as an error. VarAddress since TVM 10 is mostly useless as it throws exit code 9 in many cases.

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 that cannot be parsed as a 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, address: Address): Bool;

Extension function for the StateInit struct.

Checks if the given address corresponds to the contract address in the workchain ID 0 (basechain) derived from the StateInit self. Returns true if the addresses match and false otherwise.

This function works correctly only for basechain addresses. It may produce false positives or negatives if the specified address or the address derived from the StateInit self has a non-zero workchain ID.

Attempts to pass an Address that cannot be parsed as a StdAddress throw an exception with exit code 9: Cell underflow.

contract Parent() {
    receive() {
        let childContract = initOf Child(myAddress());

        // If you are working with contracts on the basechain, this
        let expensiveCheck = contractAddress(childContract) == sender();

        // is more expensive than doing this
        let cheaperCheck = childContract.hasSameBasechainAddress(sender());

        // while the results are the same
        expensiveCheck == cheaperCheck; // true
    }
}

contract Child(parentAddr: Address) {
    receive() {
        // Forwards surplus to the parent address by sending a message
        // with an empty body and all remaining funds from the received message
        cashback(self.parentAddr);
    }
}

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

500+ gas

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);
}