Developer Interface¶

This part of the documentation covers all the interfaces of TS4.

Main Interface¶

init(path, verbose=False, time=None)[source]¶

Initializes the library.

Parameters

path (str) – Directory where the artifacts of the used contracts are located
verbose (bool) – Toggle to print additional execution info
time (num) – Time in seconds (unixtime). TS4 uses either real-clock or virtual time. Once you set time you switch to the virtual time mode.

set_verbose(verbose=True)[source]¶

Sets verbosity mode. When verbosity is enabled all the messages and some additional stuff is printed to console. Useful for debugging.

Parameters: verbose (bool) – Toggle to print additional execution info

set_stop_at_crash(do_stop)[source]¶

Sets G_STOP_AT_CRASH global flag. By default the system stops at the first exception (unexpected exit code) raised by a contract. Use expect_ec parameter if you expected an exception in a given call. When G_STOP_AT_CRASH is disabled the system only warns user and does not stop.

Parameters: do_stop (bool) – Toggle for crash stop mode

set_config_param(index, value)[source]¶

Sets global config parameter.

Parameters

index (num) – Parameter index
value (Cell) – Cell object containing desired value.

verbose_(msg)[source]¶

Helper function to show text colored red in console. Useful when debugging.

Parameters: msg (str) – String message to be printed

verbose(msg, show_always=False, color_red=False)[source]¶

Helper function to print text message in verbose mode.

Parameters

msg (str) – String message to be printed
show_always (bool) – When enabled forces to show message even when verbose mode is off
color_red (bool) – Emphasize the message in color

reset_all()[source]¶: Resets entire TS4 state. Useful when starting new testset.

version()[source]¶

Returns current version of TestSuite4.

Returns: Current version
Return type: str

Address helpers¶

zero_addr(wc)[source]¶

Creates a zero address instance in a given workchain.

Parameters: wc (num) – Workchain ID
Returns: Object
Return type: Address

ensure_address(addr)[source]¶

Raises an error if a given object is not of Address class.

Parameters: addr (Address) – Object of class Address

Account balance¶

ensure_balance(expected, got, dismiss=False, epsilon=0, msg=None)[source]¶

Checks the contract balance for exact match. In case of mismatch prints the difference in a convenient form.

Parameters

expected (num) – Expected balance value
got (num) – Сurrent balance value
dismiss (bool) – When False don’t stop the execution in case of mismatch
epsilon (num) – Allowed difference between requested and actual balances
msg (str) – Optional message to print in case of mismatch

get_balance(addr)[source]¶

Retrieves the balance of a given address.

Parameters: addr (Address) – The address of a contract
Returns: Current account balance
Return type: num

Work with ABI¶

fix_abi(name, abi, callback)[source]¶

Travels through given ABI calling a callback function for each node

Parameters

name (str) – Contract name
abi (dict) – Contract ABI
callback – Transformation function called for each node

register_abi(contract_name)[source]¶

Loads an ABI for a given contract without its construction. Useful when some contracts are deployed indirectly (i.e. from other contracts).

Parameters: contract_name (str) – The contract name the ABI of which should be uploaded

set_contract_abi(contract, new_abi_name)[source]¶

Sets new ABI for a given contract. Useful when contract code was upgraded.

Parameters

contract (BaseContract) – An instance of the contract where the ABI will be set
new_abi_name (str) – Name of the file containing the ABI

Messages¶

pop_msg()[source]¶

Removes first message from the unprocessed messages g.QUEUE and returns it.

Returns: Object
Return type: Msg

peek_msg()[source]¶

Returns first message from the unprocessed messages g.QUEUE and leaves the g.QUEUE unchanged.

Returns: Object
Return type: Msg

pop_event()[source]¶

Removes first event from the unprocessed events g.QUEUE and returns it.

Returns: Object
Return type: Msg

peek_event()[source]¶

Returns first event from the unprocessed events g.QUEUE and leaves the g.QUEUE unchanged.

Returns: Object
Return type: Msg

queue_length()[source]¶

Returns the size of the unprocessed messages g.QUEUE.

Returns: g.QUEUE length
Return type: num

ensure_queue_empty()[source]¶: Checks if the unprocessed messages g.QUEUE is empty and raises an error if it is not. Useful for debugging.

dump_queue()[source]¶: Dumps messages g.QUEUE to the console.

Dispatching¶

dispatch_one_message(expect_ec=0)[source]¶

Takes first unprocessed message from the queue and dispatches it. Use expect_ec parameter if you expect non-zero exit code.

Parameters: expect_ec (num) – Expected exit code
Returns: The amount of gas spent on the execution of the transaction
Return type: num

dispatch_messages(callback=None)[source]¶

Dispatches all messages in the queue one by one until the queue becomes empty.

Parameters: callback – Callback to be called for each processed message. If callback returns False then the given message is skipped.

Artifacts¶

load_tvc(fn)[source]¶

Loads a compiled contract image (.tvc) with a given name.

Parameters: fn (str) – The file name
Returns: Cell object loaded from a given file
Return type: Cell

load_code_cell(fn)[source]¶

Loads contract code cell from a compiled contract image with a given name.

Parameters: fn (str) – The file name
Returns: Cell object containing contract’s code cell
Return type: Cell

load_data_cell(fn)[source]¶

Loads contract data cell from a compiled contract image with a given name.

Parameters: fn (str) – The file name
Returns: Cell object containing contract’s data cell
Return type: Cell

Other¶

register_nickname(addr, nickname)[source]¶

Registers human readable name for a given address. This name is used in verbose output.

Parameters

addr (Address) – An address of the account
nickname (str) – A nickname for the account

decode_int(v)[source]¶

Decodes integer value from hex string. Helper function useful when decoding data from contracts.

Parameters: v (str) – Hexadecimal string
Returns: Decoded number
Return type: num

make_keypair(seed=None)[source]¶

Generates random keypair.

Parameters: seed (str) – Seed to be used to generate keys. Useful when constant keypair is needed
Returns: The key pair
Return type: (str, str)

eq(v1, v2, dismiss=False, msg=None, xtra='')[source]¶

Helper function to check that two values are equal. Prints the message in case of mismatch, and optionally stops tests execution.

Parameters

v1 (Any) – Expected value
v2 (Any) – Actual value
dismiss (bool) – When False stops the entire execution in case of mismatch. When True only error message is shown
msg (str) – Optional additional message to be printed in case of mismatch
xtra (str) – Another optional additional message to be printed

Returns

Result of check

Return type

bool

set_tests_path(path)[source]¶

Sets the directory where the system will look for compiled contracts.

Parameters: path (str) – The path to contract artifacts

str2bytes(s: str) → str[source]¶

Converts string to hex representations.

Parameters: s (str) – A string to convert
Returns: Hexadecimal string
Return type: str

bytes2str(b: str) → str[source]¶

Decodes utf-8 string from hex representation

Parameters: b (str) – Hexadecimal string to convert
Returns: Decoded string
Return type: str

sign_cell(cell, private_key)[source]¶

Signs cell with a given key and returns signature.

Parameters

value (Cell) – Cell to be signed
private_key (str) – Hexadecimal representation of 1024-bits long private key

Returns

Hexadecimal string representing resulting signature

Return type

str

Classes¶

BaseContract¶

class BaseContract(name, ctor_params, wc=0, initial_data=None, address=None, override_address=None, pubkey=None, private_key=None, keypair=None, balance=None, nickname=None)[source]¶

The BaseContract object, which is responsible for deploying contracts and interaction with deployed contracts.

__init__(name, ctor_params, wc=0, initial_data=None, address=None, override_address=None, pubkey=None, private_key=None, keypair=None, balance=None, nickname=None)[source]¶

Constructs BaseContract object.

Parameters

name (str) – Name used to load contract’s bytecode and ABI
ctor_params (dict) – Parameters for offchain constructor call If None, constructor is not called and can be called with separate call_method() call (onchain constructed)
wc (num) – workchain_id to deploy contract to
initial_data (dict) – Initial data for the contract (static members)
address (Address) – If this parameter is specified no new contract is created but instead a wrapper for an existing contract is created
override_address (Address) – When specified this address will be used for deploying the contract. Otherwise the address is generated according to real blockchain rules
pubkey (str) – Public key used in contract construction
private_key (str) – Private key used to sign construction message
keypair – Keypair containing private and public keys
balance (num) – Desired contract balance
nickname (str) – Nickname of the contract used in verbose output

property balance¶

Retreives balance of a given contract.

Returns: Account balance
Return type: num

property address¶

Returns address of a given contract.

Returns: Address of contract
Return type: Address

property addr¶

Returns address of a given contract. Shorter version of address.

Returns: Address of contract
Return type: Address

call_getter_raw(method, params={}, expect_ec=0)[source]¶

Calls a given getter and returns an answer in raw JSON format.

Parameters

method (str) – Name of a getter
params (dict) – A dictionary with getter parameters
expect_ec (num) – Expected exit code. Use non-zero value if you expect a getter to raise an exception

Returns

Message parameters

Return type

JSON

call_getter(method, params={}, key=None, expect_ec=0, decode=False, decoder=None, decode_ints=None, decode_tuples=None, dont_decode_fields=None)[source]¶

Calls a given getter and decodes an answer.

Parameters

method (str) – Name of a getter
params (dict) – A dictionary with getter parameters
key (str) – (optional) If function returns tuple this parameter forces to return only one value under the desired key.
expect_ec (num) – Expected exit code. Use non-zero value if you expect a getter to raise an exception
decoder (Decoder) – Use this parameter to override decoding parameters

Returns

A returned value in decoded form (exact type depends on the type of getter)

Return type

type

decode_event(event_msg)[source]¶

Experimental feature. Decodes event parameters

Parameters: event_msg (Msg) – An event message
Returns: Event parameters in decoded form
Return type: Params

call_method(method, params={}, private_key=None, expect_ec=0, is_debot=False)[source]¶

Calls a given method.

Parameters

method (str) – Name of the method to be called
params (dict) – A dictionary with parameters for calling the contract function
private_key (str) – A private key to be used to sign the message
expect_ec (num) – Expected exit code. Use non-zero value if you expect a method to raise an exception

Returns

Value in decoded form (if method returns something)

Return type

dict

call_method_signed(method, params={}, expect_ec=0)[source]¶

Calls a given method using contract’s private key.

Parameters

method (str) – Name of the method to be called
params (dict) – A dictionary with parameters for calling the contract function
expect_ec (num) – Expected exit code. Use non-zero value if you expect a method to raise an exception

Returns

Value in decoded form (if method returns something)

Return type

dict

ticktock(is_tock)[source]¶

Simulates tick-tock call.

Parameters: is_tock (bool) – False for Tick and True for Tock
Returns: The amount of gas spent on the execution of the transaction
Return type: num

property keypair¶

Returns keypair assigned to the contract.

Returns: Account keypair
Return type: (str, str)

Address¶

class Address(addr)[source]¶

The Address object, which contains an Address entity.

__init__(addr)[source]¶

Constructs Address object.

Parameters: addr (str) – A string representing the address or None

str()[source]¶

Returns string representing given address.

Returns: A string representing the address
Return type: str

is_none()[source]¶

Checks if address is None.

Returns: Result of check
Return type: bool

fix_wc()[source]¶

Adds workchain_id if it was missing.

Returns: Object
Return type: Address

static zero_addr(wc=0)[source]¶

Creates a zero address instance in a given workchain.

Parameters: wc (num) – Workchain ID
Returns: Object
Return type: Address

static ensure_address(addr)[source]¶

Raises an error if a given object is not of Address class.

Parameters: addr (Address) – Object of class Address

Bytes¶

class Bytes(value)[source]¶

The Bytes object, which represents bytes type.

__init__(value)[source]¶

Constructs Bytes object.

Parameters: value (str) – A hexadecimal string representing array of bytes

Cell¶

class Cell(value)[source]¶

The Cell object, which represents a cell.

__init__(value)[source]¶

Constructs Cell object.

Parameters: value (str) – A base64 string representing the cell

is_empty()[source]¶

Checks if the cell is empty.

Returns: Result of check
Return type: bool

Msg¶

class Msg(data)[source]¶

The Msg object, which represents a blockchain message.

Variables

id (str) – Message ID
src (Address) – Source address
dst (Address) – Destionation address
type (str) – Type of message (empty, unknown, bounced, event, answer, external_call, call_getter)
value – The value attached to an internal message
method (str) – Called method/getter
params (dict) – A dictionary with parameters of the called method/getter

__init__(data)[source]¶

Constructs Msg object.

Parameters: data (dict) – Dictionary with message data

is_type(type1, type2=None, type3=None, type4=None, type5=None)[source]¶

Checks if a given message has one of requested types.

Parameters

type1 (str) – A name of desired type
type2 (str) – optional - A name of desired type
type3 (str) – optional - A name of desired type
type4 (str) – optional - A name of desired type
type5 (str) – optional - A name of desired type

Returns

Result of check

Return type

bool

is_type_in(types)[source]¶

Checks if a given message is one of requested types.

Parameters: types (list) – A list of strings of type names
Returns: Result of check
Return type: bool

is_answer(method=None)[source]¶

Checks if a given message is of an answer type.

Parameters: method (str) – optional - Desired name of a function answered
Returns: Result of check
Return type: bool

is_call(method=None)[source]¶

Checks if a given message is of a call type.

Parameters: method (str) – optional - Desired name of a function called
Returns: Result of check
Return type: bool

is_empty()[source]¶

Checks if a given message is of an empty type.

Returns: Result of check
Return type: bool

is_event(name=None, src=None, dst=None)[source]¶

Checks if a given message is of an event type.

Parameters

name (str) – Desired name of event to check
src (str) – Desired source address of event to check
dst (str) – Desired destination address of event to check

Returns

Result of check

Return type

bool

is_unknown()[source]¶

Checks if a current message is of an unknown type.

Returns: Result of check
Return type: bool

is_bounced()[source]¶

Checks if the given message is bounced.

Returns: Result of check
Return type: bool

is_getter()[source]¶

Checks if the given message is a getter call.

Returns: Result of check
Return type: bool

dump_data()[source]¶: Dumps message data.

Decoder¶

class Decoder(ints=None, strings=None, tuples=None, skip_fields=[])[source]¶

The Decoder object, which contains decoder settings.

Variables

ints (bool) – Whether decode integers or not
strings (bool) – Decode string or leave it as Bytes object
tuples (bool) – When getter returns tuple whether to return it as tuple or if no return as a map/dict
skip_fields (list) – The list of the field names to be skipped during decoding stage

__init__(ints=None, strings=None, tuples=None, skip_fields=[])[source]¶

Constructs Decoder object.

Parameters

ints (bool) – Whether decode integers or not
strings (bool) – Decode string or leave it as Bytes object
tuples (bool) – When getter returns tuple whether to return it as tuple or if no return as a map/dict
skip_fields (list) – The list of the field names to be skipped during decoding stage