Module client

Module client

Provides information about library.

Functions

get_api_reference – Returns Core Library API reference

version – Returns Core Library version

config – Returns Core Library API reference

build_info – Returns detailed information about this build.

resolve_app_request – Resolves application request processing result

Types

ClientErrorCode

ClientError

ClientConfig

NetworkConfig

BindingConfig

NetworkQueriesProtocol – Network protocol used to perform GraphQL queries.

CryptoConfig – Crypto config.

AbiConfig

BocConfig

ProofsConfig

BuildInfoDependency

ParamsOfAppRequest

AppRequestResultErrorVariant – Error occurred during request processing

AppRequestResultOkVariant – Request processed successfully

AppRequestResult

ResultOfGetApiReference

ResultOfVersion

ResultOfBuildInfo

ParamsOfResolveAppRequest

Functions

get_api_reference

Returns Core Library API reference

type ResultOfGetApiReference = {
    api: any
}

function get_api_reference(): Promise<ResultOfGetApiReference>;

function get_api_reference_sync(): ResultOfGetApiReference;

NOTE: Sync version is available only for lib-node binding.

Result

• api: API

version

Returns Core Library version

type ResultOfVersion = {
    version: string
}

function version(): Promise<ResultOfVersion>;

function version_sync(): ResultOfVersion;

NOTE: Sync version is available only for lib-node binding.

Result

• version: string – Core Library version

config

Returns Core Library API reference

type ClientConfig = {
    binding?: BindingConfig,
    network?: NetworkConfig,
    crypto?: CryptoConfig,
    abi?: AbiConfig,
    boc?: BocConfig,
    proofs?: ProofsConfig,
    local_storage_path?: string
}

function config(): Promise<ClientConfig>;

function config_sync(): ClientConfig;

NOTE: Sync version is available only for lib-node binding.

Result

• binding?: BindingConfig

• network?: NetworkConfig

• crypto?: CryptoConfig

• abi?: AbiConfig

• boc?: BocConfig

• proofs?: ProofsConfig

• local_storage_path?: string – For file based storage is a folder name where SDK will store its data. For browser based is a browser async storage key prefix. Default (recommended) value is "~/.tonclient" for native environments and ".tonclient" for web-browser.

build_info

Returns detailed information about this build.

type ResultOfBuildInfo = {
    build_number: number,
    dependencies: BuildInfoDependency[]
}

function build_info(): Promise<ResultOfBuildInfo>;

function build_info_sync(): ResultOfBuildInfo;

NOTE: Sync version is available only for lib-node binding.

Result

• build_number: number – Build number assigned to this build by the CI.

• dependencies: BuildInfoDependency[] – Fingerprint of the most important dependencies.

resolve_app_request

Resolves application request processing result

type ParamsOfResolveAppRequest = {
    app_request_id: number,
    result: AppRequestResult
}

function resolve_app_request(
    params: ParamsOfResolveAppRequest,
): Promise<void>;

function resolve_app_request_sync(
    params: ParamsOfResolveAppRequest,
): void;

NOTE: Sync version is available only for lib-node binding.

Parameters

• app_request_id: number – Request ID received from SDK

• result: AppRequestResult – Result of request processing

Types

ClientErrorCode

enum ClientErrorCode {
    NotImplemented = 1,
    InvalidHex = 2,
    InvalidBase64 = 3,
    InvalidAddress = 4,
    CallbackParamsCantBeConvertedToJson = 5,
    WebsocketConnectError = 6,
    WebsocketReceiveError = 7,
    WebsocketSendError = 8,
    HttpClientCreateError = 9,
    HttpRequestCreateError = 10,
    HttpRequestSendError = 11,
    HttpRequestParseError = 12,
    CallbackNotRegistered = 13,
    NetModuleNotInit = 14,
    InvalidConfig = 15,
    CannotCreateRuntime = 16,
    InvalidContextHandle = 17,
    CannotSerializeResult = 18,
    CannotSerializeError = 19,
    CannotConvertJsValueToJson = 20,
    CannotReceiveSpawnedResult = 21,
    SetTimerError = 22,
    InvalidParams = 23,
    ContractsAddressConversionFailed = 24,
    UnknownFunction = 25,
    AppRequestError = 26,
    NoSuchRequest = 27,
    CanNotSendRequestResult = 28,
    CanNotReceiveRequestResult = 29,
    CanNotParseRequestResult = 30,
    UnexpectedCallbackResponse = 31,
    CanNotParseNumber = 32,
    InternalError = 33,
    InvalidHandle = 34,
    LocalStorageError = 35,
    InvalidData = 36
}

One of the following value:

• NotImplemented = 1

• InvalidHex = 2

• InvalidBase64 = 3

• InvalidAddress = 4

• CallbackParamsCantBeConvertedToJson = 5

• WebsocketConnectError = 6

• WebsocketReceiveError = 7

• WebsocketSendError = 8

• HttpClientCreateError = 9

• HttpRequestCreateError = 10

• HttpRequestSendError = 11

• HttpRequestParseError = 12

• CallbackNotRegistered = 13

• NetModuleNotInit = 14

• InvalidConfig = 15

• CannotCreateRuntime = 16

• InvalidContextHandle = 17

• CannotSerializeResult = 18

• CannotSerializeError = 19

• CannotConvertJsValueToJson = 20

• CannotReceiveSpawnedResult = 21

• SetTimerError = 22

• InvalidParams = 23

• ContractsAddressConversionFailed = 24

• UnknownFunction = 25

• AppRequestError = 26

• NoSuchRequest = 27

• CanNotSendRequestResult = 28

• CanNotReceiveRequestResult = 29

• CanNotParseRequestResult = 30

• UnexpectedCallbackResponse = 31

• CanNotParseNumber = 32

• InternalError = 33

• InvalidHandle = 34

• LocalStorageError = 35

• InvalidData = 36

ClientError

type ClientError = {
    code: number,
    message: string,
    data: any
}

• code: number

• message: string

• data: any

ClientConfig

type ClientConfig = {
    binding?: BindingConfig,
    network?: NetworkConfig,
    crypto?: CryptoConfig,
    abi?: AbiConfig,
    boc?: BocConfig,
    proofs?: ProofsConfig,
    local_storage_path?: string
}

• binding?: BindingConfig

• network?: NetworkConfig

• crypto?: CryptoConfig

• abi?: AbiConfig

• boc?: BocConfig

• proofs?: ProofsConfig

• local_storage_path?: string – For file based storage is a folder name where SDK will store its data. For browser based is a browser async storage key prefix. Default (recommended) value is "~/.tonclient" for native environments and ".tonclient" for web-browser.

NetworkConfig

type NetworkConfig = {
    server_address?: string,
    endpoints?: string[],
    network_retries_count?: number,
    max_reconnect_timeout?: number,
    reconnect_timeout?: number,
    message_retries_count?: number,
    message_processing_timeout?: number,
    wait_for_timeout?: number,
    out_of_sync_threshold?: number,
    sending_endpoint_count?: number,
    latency_detection_interval?: number,
    max_latency?: number,
    query_timeout?: number,
    queries_protocol?: NetworkQueriesProtocol,
    first_remp_status_timeout?: number,
    next_remp_status_timeout?: number,
    signature_id?: number,
    access_key?: string
}

• server_address?: string – This field is deprecated, but left for backward-compatibility. Evernode endpoint.

• endpoints?: string[] – List of Evernode endpoints. Any correct URL format can be specified, including IP addresses. This parameter is prevailing over server_address. Check the full list of supported network endpoints.

• network_retries_count?: number – Deprecated. You must use network.max_reconnect_timeout that allows to specify maximum network resolving timeout.

• max_reconnect_timeout?: number – Maximum time for sequential reconnections. Must be specified in milliseconds. Default is 120000 (2 min).

• reconnect_timeout?: number – Deprecated

• message_retries_count?: number – The number of automatic message processing retries that SDK performs in case of Message Expired (507) error - but only for those messages which local emulation was successful or failed with replay protection error. Default is 5.

• message_processing_timeout?: number – Timeout that is used to process message delivery for the contracts which ABI does not include "expire" header. If the message is not delivered within the specified timeout the appropriate error occurs. Must be specified in milliseconds. Default is 40000 (40 sec).

• wait_for_timeout?: number – Maximum timeout that is used for query response. Must be specified in milliseconds. Default is 40000 (40 sec).

• out_of_sync_threshold?: number – DEPRECATED: This parameter was deprecated.

• sending_endpoint_count?: number – Maximum number of randomly chosen endpoints the library uses to broadcast a message. Default is 1.

• latency_detection_interval?: number – Frequency of sync latency detection. Library periodically checks the current endpoint for blockchain data synchronization latency. If the latency (time-lag) is less then NetworkConfig.max_latency then library selects another endpoint. Must be specified in milliseconds. Default is 60000 (1 min).

• max_latency?: number – Maximum value for the endpoint's blockchain data synchronization latency (time-lag). Library periodically checks the current endpoint for blockchain data synchronization latency. If the latency (time-lag) is less then NetworkConfig.max_latency then library selects another endpoint. Must be specified in milliseconds. Default is 60000 (1 min).

• query_timeout?: number – Default timeout for http requests. Is is used when no timeout specified for the request to limit the answer waiting time. If no answer received during the timeout requests ends with error. Must be specified in milliseconds. Default is 60000 (1 min).

• queries_protocol?: NetworkQueriesProtocol – Queries protocol. HTTP or WS. Default is HTTP.

• first_remp_status_timeout?: number – UNSTABLE. First REMP status awaiting timeout. If no status received during the timeout than fallback transaction scenario is activated. Must be specified in milliseconds. Default is 1 (1 ms) in order to start fallback scenario together with REMP statuses processing while REMP is not properly tuned yet.

• next_remp_status_timeout?: number – UNSTABLE. Subsequent REMP status awaiting timeout. If no status received during the timeout than fallback transaction scenario is activated. Must be specified in milliseconds. Default is 5000 (5 sec).

• signature_id?: number – Network signature ID which is used by VM in signature verifying instructions if capability CapSignatureWithId is enabled in blockchain configuration parameters. This parameter should be set to global_id field from any blockchain block if network can not be reachable at the moment of message encoding and the message is aimed to be sent into network with CapSignatureWithId enabled. Otherwise signature ID is detected automatically inside message encoding functions

• access_key?: string – Access key to GraphQL API (Project secret)

BindingConfig

type BindingConfig = {
    library?: string,
    version?: string
}

• library?: string

• version?: string

NetworkQueriesProtocol

Network protocol used to perform GraphQL queries.

enum NetworkQueriesProtocol {
    HTTP = "HTTP",
    WS = "WS"
}

One of the following value:

• HTTP = "HTTP" – Each GraphQL query uses separate HTTP request.

• WS = "WS" – All GraphQL queries will be served using single web socket connection. SDK is tested to reliably handle 5000 parallel network requests (sending and processing messages, quering and awaiting blockchain data)

CryptoConfig

Crypto config.

type CryptoConfig = {
    mnemonic_dictionary?: MnemonicDictionary,
    mnemonic_word_count?: number,
    hdkey_derivation_path?: string
}

• mnemonic_dictionary?: MnemonicDictionary – Mnemonic dictionary that will be used by default in crypto functions. If not specified, English dictionary will be used.

• mnemonic_word_count?: number – Mnemonic word count that will be used by default in crypto functions. If not specified the default value will be 12.

• hdkey_derivation_path?: string – Derivation path that will be used by default in crypto functions. If not specified m/44'/396'/0'/0/0 will be used.

AbiConfig

type AbiConfig = {
    workchain?: number,
    message_expiration_timeout?: number,
    message_expiration_timeout_grow_factor?: number
}

• workchain?: number – Workchain id that is used by default in DeploySet

• message_expiration_timeout?: number – Message lifetime for contracts which ABI includes "expire" header. Must be specified in milliseconds. Default is 40000 (40 sec).

• message_expiration_timeout_grow_factor?: number – Factor that increases the expiration timeout for each retry Default is 1.5

BocConfig

type BocConfig = {
    cache_max_size?: number
}

• cache_max_size?: number – Maximum BOC cache size in kilobytes. Default is 10 MB

ProofsConfig

type ProofsConfig = {
    cache_in_local_storage?: boolean
}

• cache_in_local_storage?: boolean – Cache proofs in the local storage. Default is true. If this value is set to true, downloaded proofs and master-chain BOCs are saved into the persistent local storage (e.g. file system for native environments or browser's IndexedDB for the web); otherwise all the data is cached only in memory in current client's context and will be lost after destruction of the client.

BuildInfoDependency

type BuildInfoDependency = {
    name: string,
    git_commit: string
}

• name: string – Dependency name. Usually it is a crate name.

• git_commit: string – Git commit hash of the related repository.

ParamsOfAppRequest

type ParamsOfAppRequest = {
    app_request_id: number,
    request_data: any
}

• app_request_id: number – Request ID. Should be used in resolve_app_request call

• request_data: any – Request describing data

AppRequestResultErrorVariant

Error occurred during request processing

type AppRequestResultErrorVariant = {
    text: string
}

• text: string – Error description

AppRequestResultOkVariant

Request processed successfully

type AppRequestResultOkVariant = {
    result: any
}

• result: any – Request processing result

AppRequestResult

type AppRequestResult = ({
    type: 'Error'
} & AppRequestResultErrorVariant) | ({
    type: 'Ok'
} & AppRequestResultOkVariant)

Depends on value of the type field.

When type is 'Error'

Error occurred during request processing

• text: string – Error description

When type is 'Ok'

Request processed successfully

• result: any – Request processing result

Variant constructors:

function appRequestResultError(text: string): AppRequestResult;
function appRequestResultOk(result: any): AppRequestResult;

ResultOfGetApiReference

type ResultOfGetApiReference = {
    api: any
}

• api: API

ResultOfVersion

type ResultOfVersion = {
    version: string
}

• version: string – Core Library version

ResultOfBuildInfo

type ResultOfBuildInfo = {
    build_number: number,
    dependencies: BuildInfoDependency[]
}

• build_number: number – Build number assigned to this build by the CI.

• dependencies: BuildInfoDependency[] – Fingerprint of the most important dependencies.

ParamsOfResolveAppRequest

type ParamsOfResolveAppRequest = {
    app_request_id: number,
    result: AppRequestResult
}

• app_request_id: number – Request ID received from SDK

• result: AppRequestResult – Result of request processing