Skip to content

Latest commit

 

History

History
935 lines (688 loc) · 23.7 KB

mod_net.md

File metadata and controls

935 lines (688 loc) · 23.7 KB

Module net

Network access.

Functions

query – Performs DAppServer GraphQL query.

batch_query – Performs multiple queries per single fetch.

query_collection – Queries collection data

aggregate_collection – Aggregates collection data.

wait_for_collection – Returns an object that fulfills the conditions or waits for its appearance

unsubscribe – Cancels a subscription

subscribe_collection – Creates a subscription

suspend – Suspends network module to stop any network activity

resume – Resumes network module to enable network activity

find_last_shard_block – Returns ID of the last block in a specified account shard

fetch_endpoints – Requests the list of alternative endpoints from server

set_endpoints – Sets the list of endpoints to use on reinit

get_endpoints – Requests the list of alternative endpoints from server

query_counterparties – Allows to query and paginate through the list of accounts that the specified account has interacted with, sorted by the time of the last internal message between accounts

query_transaction_tree – Returns transactions tree for specific message.

Types

NetErrorCode

OrderBy

SortDirection

ParamsOfQueryOperation

FieldAggregation

AggregationFn

TransactionNode

MessageNode

ParamsOfQuery

ResultOfQuery

ParamsOfBatchQuery

ResultOfBatchQuery

ParamsOfQueryCollection

ResultOfQueryCollection

ParamsOfAggregateCollection

ResultOfAggregateCollection

ParamsOfWaitForCollection

ResultOfWaitForCollection

ResultOfSubscribeCollection

ParamsOfSubscribeCollection

ParamsOfFindLastShardBlock

ResultOfFindLastShardBlock

EndpointsSet

ResultOfGetEndpoints

ParamsOfQueryCounterparties

ParamsOfQueryTransactionTree

ResultOfQueryTransactionTree

Functions

query

Performs DAppServer GraphQL query.

type ParamsOfQuery = {
    query: string,
    variables?: any
}

type ResultOfQuery = {
    result: any
}

function query(
    params: ParamsOfQuery,
): Promise<ResultOfQuery>;

Parameters

  • query: string – GraphQL query text.
  • variables?: any – Variables used in query.
    Must be a map with named values that can be used in query.

Result

  • result: any – Result provided by DAppServer.

batch_query

Performs multiple queries per single fetch.

type ParamsOfBatchQuery = {
    operations: ParamsOfQueryOperation[]
}

type ResultOfBatchQuery = {
    results: any[]
}

function batch_query(
    params: ParamsOfBatchQuery,
): Promise<ResultOfBatchQuery>;

Parameters

Result

  • results: any[] – Result values for batched queries.
    Returns an array of values. Each value corresponds to queries item.

query_collection

Queries collection data

Queries data that satisfies the filter conditions, limits the number of returned records and orders them. The projection fields are limited to result fields

type ParamsOfQueryCollection = {
    collection: string,
    filter?: any,
    result: string,
    order?: OrderBy[],
    limit?: number
}

type ResultOfQueryCollection = {
    result: any[]
}

function query_collection(
    params: ParamsOfQueryCollection,
): Promise<ResultOfQueryCollection>;

Parameters

  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string
  • order?: OrderBy[] – Sorting order
  • limit?: number – Number of documents to return

Result

  • result: any[] – Objects that match the provided criteria

aggregate_collection

Aggregates collection data.

Aggregates values from the specified fields for records that satisfies the filter conditions,

type ParamsOfAggregateCollection = {
    collection: string,
    filter?: any,
    fields?: FieldAggregation[]
}

type ResultOfAggregateCollection = {
    values: any
}

function aggregate_collection(
    params: ParamsOfAggregateCollection,
): Promise<ResultOfAggregateCollection>;

Parameters

  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • fields?: FieldAggregation[] – Projection (result) string

Result

  • values: any – Values for requested fields.
    Returns an array of strings. Each string refers to the corresponding fields item.
    Numeric value is returned as a decimal string representations.

wait_for_collection

Returns an object that fulfills the conditions or waits for its appearance

Triggers only once. If object that satisfies the filter conditions already exists - returns it immediately. If not - waits for insert/update of data within the specified timeout, and returns it. The projection fields are limited to result fields

type ParamsOfWaitForCollection = {
    collection: string,
    filter?: any,
    result: string,
    timeout?: number
}

type ResultOfWaitForCollection = {
    result: any
}

function wait_for_collection(
    params: ParamsOfWaitForCollection,
): Promise<ResultOfWaitForCollection>;

Parameters

  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string
  • timeout?: number – Query timeout

Result

  • result: any – First found object that matches the provided criteria

unsubscribe

Cancels a subscription

Cancels a subscription specified by its handle.

type ResultOfSubscribeCollection = {
    handle: number
}

function unsubscribe(
    params: ResultOfSubscribeCollection,
): Promise<void>;

Parameters

  • handle: number – Subscription handle.
    Must be closed with unsubscribe

subscribe_collection

Creates a subscription

Triggers for each insert/update of data that satisfies the filter conditions. The projection fields are limited to result fields.

The subscription is a persistent communication channel between client and Free TON Network. All changes in the blockchain will be reflected in realtime. Changes means inserts and updates of the blockchain entities.

Important Notes on Subscriptions

Unfortunately sometimes the connection with the network brakes down. In this situation the library attempts to reconnect to the network. This reconnection sequence can take significant time. All of this time the client is disconnected from the network.

Bad news is that all blockchain changes that happened while the client was disconnected are lost.

Good news is that the client report errors to the callback when it loses and resumes connection.

So, if the lost changes are important to the application then the application must handle these error reports.

Library reports errors with responseType == 101 and the error object passed via params.

When the library has successfully reconnected the application receives callback with responseType == 101 and params.code == 614 (NetworkModuleResumed).

Application can use several ways to handle this situation:

  • If application monitors changes for the single blockchain object (for example specific account): application can perform a query for this object and handle actual data as a regular data from the subscription.
  • If application monitors sequence of some blockchain objects (for example transactions of the specific account): application must refresh all cached (or visible to user) lists where this sequences presents.
type ParamsOfSubscribeCollection = {
    collection: string,
    filter?: any,
    result: string
}

type ResultOfSubscribeCollection = {
    handle: number
}

function subscribe_collection(
    params: ParamsOfSubscribeCollection,
    responseHandler?: ResponseHandler,
): Promise<ResultOfSubscribeCollection>;

Parameters

  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string
  • responseHandler?: ResponseHandler – additional responses handler.

Result

  • handle: number – Subscription handle.
    Must be closed with unsubscribe

suspend

Suspends network module to stop any network activity

function suspend(): Promise<void>;

resume

Resumes network module to enable network activity

function resume(): Promise<void>;

find_last_shard_block

Returns ID of the last block in a specified account shard

type ParamsOfFindLastShardBlock = {
    address: string
}

type ResultOfFindLastShardBlock = {
    block_id: string
}

function find_last_shard_block(
    params: ParamsOfFindLastShardBlock,
): Promise<ResultOfFindLastShardBlock>;

Parameters

  • address: string – Account address

Result

  • block_id: string – Account shard last block ID

fetch_endpoints

Requests the list of alternative endpoints from server

type EndpointsSet = {
    endpoints: string[]
}

function fetch_endpoints(): Promise<EndpointsSet>;

Result

  • endpoints: string[] – List of endpoints provided by server

set_endpoints

Sets the list of endpoints to use on reinit

type EndpointsSet = {
    endpoints: string[]
}

function set_endpoints(
    params: EndpointsSet,
): Promise<void>;

Parameters

  • endpoints: string[] – List of endpoints provided by server

get_endpoints

Requests the list of alternative endpoints from server

type ResultOfGetEndpoints = {
    query: string,
    endpoints: string[]
}

function get_endpoints(): Promise<ResultOfGetEndpoints>;

Result

  • query: string – Current query endpoint
  • endpoints: string[] – List of all endpoints used by client

query_counterparties

Allows to query and paginate through the list of accounts that the specified account has interacted with, sorted by the time of the last internal message between accounts

Attention this query retrieves data from 'Counterparties' service which is not supported in the opensource version of DApp Server (and will not be supported) as well as in TON OS SE (will be supported in SE in future), but is always accessible via TON OS Devnet/Mainnet Clouds

type ParamsOfQueryCounterparties = {
    account: string,
    result: string,
    first?: number,
    after?: string
}

type ResultOfQueryCollection = {
    result: any[]
}

function query_counterparties(
    params: ParamsOfQueryCounterparties,
): Promise<ResultOfQueryCollection>;

Parameters

  • account: string – Account address
  • result: string – Projection (result) string
  • first?: number – Number of counterparties to return
  • after?: string – cursor field of the last received result

Result

  • result: any[] – Objects that match the provided criteria

query_transaction_tree

Returns transactions tree for specific message.

Performs recursive retrieval of the transactions tree produced by the specific message: in_msg -> dst_transaction -> out_messages -> dst_transaction -> ...

All retrieved messages and transactions will be included into result.messages and result.transactions respectively.

The retrieval process will stop when the retrieved transaction count is more than 50.

It is guaranteed that each message in result.messages has the corresponding transaction in the result.transactions.

But there are no guaranties that all messages from transactions out_msgs are presented in result.messages. So the application have to continue retrieval for missing messages if it requires.

type ParamsOfQueryTransactionTree = {
    in_msg: string,
    abi_registry?: Abi[]
}

type ResultOfQueryTransactionTree = {
    messages: MessageNode[],
    transactions: TransactionNode[]
}

function query_transaction_tree(
    params: ParamsOfQueryTransactionTree,
): Promise<ResultOfQueryTransactionTree>;

Parameters

  • in_msg: string – Input message id.
  • abi_registry?: Abi[] – List of contract ABIs that will be used to decode message bodies. Library will try to decode each returned message body using any ABI from the registry.

Result

Types

NetErrorCode

enum NetErrorCode {
    QueryFailed = 601,
    SubscribeFailed = 602,
    WaitForFailed = 603,
    GetSubscriptionResultFailed = 604,
    InvalidServerResponse = 605,
    ClockOutOfSync = 606,
    WaitForTimeout = 607,
    GraphqlError = 608,
    NetworkModuleSuspended = 609,
    WebsocketDisconnected = 610,
    NotSupported = 611,
    NoEndpointsProvided = 612,
    GraphqlWebsocketInitError = 613,
    NetworkModuleResumed = 614
}

One of the following value:

  • QueryFailed = 601
  • SubscribeFailed = 602
  • WaitForFailed = 603
  • GetSubscriptionResultFailed = 604
  • InvalidServerResponse = 605
  • ClockOutOfSync = 606
  • WaitForTimeout = 607
  • GraphqlError = 608
  • NetworkModuleSuspended = 609
  • WebsocketDisconnected = 610
  • NotSupported = 611
  • NoEndpointsProvided = 612
  • GraphqlWebsocketInitError = 613
  • NetworkModuleResumed = 614

OrderBy

type OrderBy = {
    path: string,
    direction: SortDirection
}

SortDirection

enum SortDirection {
    ASC = "ASC",
    DESC = "DESC"
}

One of the following value:

  • ASC = "ASC"
  • DESC = "DESC"

ParamsOfQueryOperation

type ParamsOfQueryOperation = ({
    type: 'QueryCollection'
} & ParamsOfQueryCollection) | ({
    type: 'WaitForCollection'
} & ParamsOfWaitForCollection) | ({
    type: 'AggregateCollection'
} & ParamsOfAggregateCollection) | ({
    type: 'QueryCounterparties'
} & ParamsOfQueryCounterparties)

Depends on value of the type field.

When type is 'QueryCollection'

  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string
  • order?: OrderBy[] – Sorting order
  • limit?: number – Number of documents to return

When type is 'WaitForCollection'

  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string
  • timeout?: number – Query timeout

When type is 'AggregateCollection'

  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • fields?: FieldAggregation[] – Projection (result) string

When type is 'QueryCounterparties'

  • account: string – Account address
  • result: string – Projection (result) string
  • first?: number – Number of counterparties to return
  • after?: string – cursor field of the last received result

Variant constructors:

function paramsOfQueryOperationQueryCollection(params: ParamsOfQueryCollection): ParamsOfQueryOperation;
function paramsOfQueryOperationWaitForCollection(params: ParamsOfWaitForCollection): ParamsOfQueryOperation;
function paramsOfQueryOperationAggregateCollection(params: ParamsOfAggregateCollection): ParamsOfQueryOperation;
function paramsOfQueryOperationQueryCounterparties(params: ParamsOfQueryCounterparties): ParamsOfQueryOperation;

FieldAggregation

type FieldAggregation = {
    field: string,
    fn: AggregationFn
}
  • field: string – Dot separated path to the field
  • fn: AggregationFn – Aggregation function that must be applied to field values

AggregationFn

enum AggregationFn {
    COUNT = "COUNT",
    MIN = "MIN",
    MAX = "MAX",
    SUM = "SUM",
    AVERAGE = "AVERAGE"
}

One of the following value:

  • COUNT = "COUNT" – Returns count of filtered record
  • MIN = "MIN" – Returns the minimal value for a field in filtered records
  • MAX = "MAX" – Returns the maximal value for a field in filtered records
  • SUM = "SUM" – Returns a sum of values for a field in filtered records
  • AVERAGE = "AVERAGE" – Returns an average value for a field in filtered records

TransactionNode

type TransactionNode = {
    id: string,
    in_msg: string,
    out_msgs: string[],
    account_addr: string,
    total_fees: string,
    aborted: boolean,
    exit_code?: number
}
  • id: string – Transaction id.
  • in_msg: string – In message id.
  • out_msgs: string[] – Out message ids.
  • account_addr: string – Account address.
  • total_fees: string – Transactions total fees.
  • aborted: boolean – Aborted flag.
  • exit_code?: number – Compute phase exit code.

MessageNode

type MessageNode = {
    id: string,
    src_transaction_id?: string,
    dst_transaction_id?: string,
    src?: string,
    dst?: string,
    value?: string,
    bounce: boolean,
    decoded_body?: DecodedMessageBody
}
  • id: string – Message id.
  • src_transaction_id?: string – Source transaction id.
    This field is missing for an external inbound messages.
  • dst_transaction_id?: string – Destination transaction id.
    This field is missing for an external outbound messages.
  • src?: string – Source address.
  • dst?: string – Destination address.
  • value?: string – Transferred tokens value.
  • bounce: boolean – Bounce flag.
  • decoded_body?: DecodedMessageBody – Decoded body.
    Library tries to decode message body using provided params.abi_registry.
    This field will be missing if none of the provided abi can be used to decode.

ParamsOfQuery

type ParamsOfQuery = {
    query: string,
    variables?: any
}
  • query: string – GraphQL query text.
  • variables?: any – Variables used in query.
    Must be a map with named values that can be used in query.

ResultOfQuery

type ResultOfQuery = {
    result: any
}
  • result: any – Result provided by DAppServer.

ParamsOfBatchQuery

type ParamsOfBatchQuery = {
    operations: ParamsOfQueryOperation[]
}

ResultOfBatchQuery

type ResultOfBatchQuery = {
    results: any[]
}
  • results: any[] – Result values for batched queries.
    Returns an array of values. Each value corresponds to queries item.

ParamsOfQueryCollection

type ParamsOfQueryCollection = {
    collection: string,
    filter?: any,
    result: string,
    order?: OrderBy[],
    limit?: number
}
  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string
  • order?: OrderBy[] – Sorting order
  • limit?: number – Number of documents to return

ResultOfQueryCollection

type ResultOfQueryCollection = {
    result: any[]
}
  • result: any[] – Objects that match the provided criteria

ParamsOfAggregateCollection

type ParamsOfAggregateCollection = {
    collection: string,
    filter?: any,
    fields?: FieldAggregation[]
}
  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • fields?: FieldAggregation[] – Projection (result) string

ResultOfAggregateCollection

type ResultOfAggregateCollection = {
    values: any
}
  • values: any – Values for requested fields.
    Returns an array of strings. Each string refers to the corresponding fields item.
    Numeric value is returned as a decimal string representations.

ParamsOfWaitForCollection

type ParamsOfWaitForCollection = {
    collection: string,
    filter?: any,
    result: string,
    timeout?: number
}
  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string
  • timeout?: number – Query timeout

ResultOfWaitForCollection

type ResultOfWaitForCollection = {
    result: any
}
  • result: any – First found object that matches the provided criteria

ResultOfSubscribeCollection

type ResultOfSubscribeCollection = {
    handle: number
}
  • handle: number – Subscription handle.
    Must be closed with unsubscribe

ParamsOfSubscribeCollection

type ParamsOfSubscribeCollection = {
    collection: string,
    filter?: any,
    result: string
}
  • collection: string – Collection name (accounts, blocks, transactions, messages, block_signatures)
  • filter?: any – Collection filter
  • result: string – Projection (result) string

ParamsOfFindLastShardBlock

type ParamsOfFindLastShardBlock = {
    address: string
}
  • address: string – Account address

ResultOfFindLastShardBlock

type ResultOfFindLastShardBlock = {
    block_id: string
}
  • block_id: string – Account shard last block ID

EndpointsSet

type EndpointsSet = {
    endpoints: string[]
}
  • endpoints: string[] – List of endpoints provided by server

ResultOfGetEndpoints

type ResultOfGetEndpoints = {
    query: string,
    endpoints: string[]
}
  • query: string – Current query endpoint
  • endpoints: string[] – List of all endpoints used by client

ParamsOfQueryCounterparties

type ParamsOfQueryCounterparties = {
    account: string,
    result: string,
    first?: number,
    after?: string
}
  • account: string – Account address
  • result: string – Projection (result) string
  • first?: number – Number of counterparties to return
  • after?: string – cursor field of the last received result

ParamsOfQueryTransactionTree

type ParamsOfQueryTransactionTree = {
    in_msg: string,
    abi_registry?: Abi[]
}
  • in_msg: string – Input message id.
  • abi_registry?: Abi[] – List of contract ABIs that will be used to decode message bodies. Library will try to decode each returned message body using any ABI from the registry.

ResultOfQueryTransactionTree

type ResultOfQueryTransactionTree = {
    messages: MessageNode[],
    transactions: TransactionNode[]
}