Links

Module processing

Module processing

Message processing module.
This module incorporates functions related to complex message processing scenarios.

Functions

monitor_messages – Starts monitoring for the processing results of the specified messages.
get_monitor_info – Returns summary information about current state of the specified monitoring queue.
fetch_next_monitor_results – Fetches next resolved results from the specified monitoring queue.
cancel_monitor – Cancels all background activity and releases all allocated system resources for the specified monitoring queue.
send_messages – Sends specified messages to the blockchain.
send_message – Sends message to the network
wait_for_transaction – Performs monitoring of the network for the result transaction of the external inbound message processing.
process_message – Creates message, sends it to the network and monitors its processing.

Types

ProcessingEventWillFetchFirstBlockVariant – Notifies the application that the account's current shard block will be fetched from the network. This step is performed before the message sending so that sdk knows starting from which block it will search for the transaction.
ProcessingEventFetchFirstBlockFailedVariant – Notifies the app that the client has failed to fetch the account's current shard block.
ProcessingEventWillSendVariant – Notifies the app that the message will be sent to the network. This event means that the account's current shard block was successfully fetched and the message was successfully created (abi.encode_message function was executed successfully).
ProcessingEventDidSendVariant – Notifies the app that the message was sent to the network, i.e processing.send_message was successfully executed. Now, the message is in the blockchain. If Application exits at this phase, Developer needs to proceed with processing after the application is restored with wait_for_transaction function, passing shard_block_id and message from this event.
ProcessingEventSendFailedVariant – Notifies the app that the sending operation was failed with network error.
ProcessingEventWillFetchNextBlockVariant – Notifies the app that the next shard block will be fetched from the network.
ProcessingEventFetchNextBlockFailedVariant – Notifies the app that the next block can't be fetched.
ProcessingEventMessageExpiredVariant – Notifies the app that the message was not executed within expire timeout on-chain and will never be because it is already expired. The expiration timeout can be configured with AbiConfig parameters.
ProcessingEventRempSentToValidatorsVariant – Notifies the app that the message has been delivered to the thread's validators
ProcessingEventRempIncludedIntoBlockVariant – Notifies the app that the message has been successfully included into a block candidate by the thread's collator
ProcessingEventRempIncludedIntoAcceptedBlockVariant – Notifies the app that the block candidate with the message has been accepted by the thread's validators
ProcessingEventRempOtherVariant – Notifies the app about some other minor REMP statuses occurring during message processing
ProcessingEventRempErrorVariant – Notifies the app about any problem that has occurred in REMP processing - in this case library switches to the fallback transaction awaiting scenario (sequential block reading).
MonitoredMessageBocVariant – BOC of the message.
MonitoredMessageHashAddressVariant – Message's hash and destination address.

Functions

monitor_messages

Starts monitoring for the processing results of the specified messages.
Message monitor performs background monitoring for a message processing results for the specified set of messages.
Message monitor can serve several isolated monitoring queues. Each monitor queue has a unique application defined identifier (or name) used to separate several queue's.
There are two important lists inside of the monitoring queue:
  • unresolved messages: contains messages requested by the application for monitoring and not yet resolved;
  • resolved results: contains resolved processing results for monitored messages.
Each monitoring queue tracks own unresolved and resolved lists. Application can add more messages to the monitoring queue at any time.
Message monitor accumulates resolved results. Application should fetch this results with fetchNextMonitorResults function.
When both unresolved and resolved lists becomes empty, monitor stops any background activity and frees all allocated internal memory.
If monitoring queue with specified name already exists then messages will be added to the unresolved list.
If monitoring queue with specified name does not exist then monitoring queue will be created with specified unresolved messages.
type ParamsOfMonitorMessages = {
queue: string,
messages: MessageMonitoringParams[]
}
function monitor_messages(
params: ParamsOfMonitorMessages,
): Promise<void>;
function monitor_messages_sync(
params: ParamsOfMonitorMessages,
): void;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • queue: string – Name of the monitoring queue.
  • messages: MessageMonitoringParams[] – Messages to start monitoring for.

get_monitor_info

Returns summary information about current state of the specified monitoring queue.
type ParamsOfGetMonitorInfo = {
queue: string
}
type MonitoringQueueInfo = {
unresolved: number,
resolved: number
}
function get_monitor_info(
params: ParamsOfGetMonitorInfo,
): Promise<MonitoringQueueInfo>;
function get_monitor_info_sync(
params: ParamsOfGetMonitorInfo,
): MonitoringQueueInfo;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • queue: string – Name of the monitoring queue.

Result

  • unresolved: number – Count of the unresolved messages.
  • resolved: number – Count of resolved results.

fetch_next_monitor_results

Fetches next resolved results from the specified monitoring queue.
Results and waiting options are depends on the wait parameter. All returned results will be removed from the queue's resolved list.
type ParamsOfFetchNextMonitorResults = {
queue: string,
wait_mode?: MonitorFetchWaitMode
}
type ResultOfFetchNextMonitorResults = {
results: MessageMonitoringResult[]
}
function fetch_next_monitor_results(
params: ParamsOfFetchNextMonitorResults,
): Promise<ResultOfFetchNextMonitorResults>;
function fetch_next_monitor_results_sync(
params: ParamsOfFetchNextMonitorResults,
): ResultOfFetchNextMonitorResults;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • queue: string – Name of the monitoring queue.
  • wait_mode?: MonitorFetchWaitMode – Wait mode. Default is NO_WAIT.

Result

cancel_monitor

Cancels all background activity and releases all allocated system resources for the specified monitoring queue.
type ParamsOfCancelMonitor = {
queue: string
}
function cancel_monitor(
params: ParamsOfCancelMonitor,
): Promise<void>;
function cancel_monitor_sync(
params: ParamsOfCancelMonitor,
): void;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • queue: string – Name of the monitoring queue.

send_messages

Sends specified messages to the blockchain.
type ParamsOfSendMessages = {
messages: MessageSendingParams[],
monitor_queue?: string
}
type ResultOfSendMessages = {
messages: MessageMonitoringParams[]
}
function send_messages(
params: ParamsOfSendMessages,
): Promise<ResultOfSendMessages>;
function send_messages_sync(
params: ParamsOfSendMessages,
): ResultOfSendMessages;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • messages: MessageSendingParams[] – Messages that must be sent to the blockchain.
  • monitor_queue?: string – Optional message monitor queue that starts monitoring for the processing results for sent messages.

Result

send_message

Sends message to the network
Sends message to the network and returns the last generated shard block of the destination account before the message was sent. It will be required later for message processing.
type ParamsOfSendMessage = {
message: string,
abi?: Abi,
send_events?: boolean
}
type ResultOfSendMessage = {
shard_block_id: string,
sending_endpoints: string[]
}
function send_message(
params: ParamsOfSendMessage,
responseHandler?: ResponseHandler,
): Promise<ResultOfSendMessage>;
function send_message_sync(
params: ParamsOfSendMessage,
): ResultOfSendMessage;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • message: string – Message BOC.
  • abi?: Abi – Optional message ABI. If this parameter is specified and the message has the expire header then expiration time will be checked against the current time to prevent unnecessary sending of already expired message. The message already expired error will be returned in this case. Note, that specifying abi for ABI compliant contracts is strongly recommended, so that proper processing strategy can be chosen.
  • send_events?: boolean – Flag for requesting events sending. Default is false.
  • responseHandler?: ResponseHandler – additional responses handler.

Result

  • shard_block_id: string – The last generated shard block of the message destination account before the message was sent. This block id must be used as a parameter of the wait_for_transaction.
  • sending_endpoints: string[] – The list of endpoints to which the message was sent. This list id must be used as a parameter of the wait_for_transaction.

wait_for_transaction

Performs monitoring of the network for the result transaction of the external inbound message processing.
send_events enables intermediate events, such as WillFetchNextBlock, FetchNextBlockFailed that may be useful for logging of new shard blocks creation during message processing.
Note, that presence of the abi parameter is critical for ABI compliant contracts. Message processing uses drastically different strategy for processing message for contracts which ABI includes "expire" header.
When the ABI header expire is present, the processing uses message expiration strategy:
  • The maximum block gen time is set to message_expiration_timeout + transaction_wait_timeout.
  • When maximum block gen time is reached, the processing will be finished with MessageExpired error.
When the ABI header expire isn't present or abi parameter isn't specified, the processing uses transaction waiting strategy:
  • The maximum block gen time is set to now() + transaction_wait_timeout.
  • If maximum block gen time is reached and no result transaction is found, the processing will exit with an error.
type ParamsOfWaitForTransaction = {
abi?: Abi,
message: string,
shard_block_id: string,
send_events?: boolean,
sending_endpoints?: string[]
}
type ResultOfProcessMessage = {
transaction: any,
out_messages: string[],
decoded?: DecodedOutput,
fees: TransactionFees
}
function wait_for_transaction(
params: ParamsOfWaitForTransaction,
responseHandler?: ResponseHandler,
): Promise<ResultOfProcessMessage>;
function wait_for_transaction_sync(
params: ParamsOfWaitForTransaction,
): ResultOfProcessMessage;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi?: Abi – Optional ABI for decoding the transaction result. If it is specified, then the output messages' bodies will be decoded according to this ABI. The abi_decoded result field will be filled out.
  • message: string – Message BOC. Encoded with base64.
  • shard_block_id: string – The last generated block id of the destination account shard before the message was sent. You must provide the same value as the send_message has returned.
  • send_events?: boolean – Flag that enables/disables intermediate events. Default is false.
  • sending_endpoints?: string[] – The list of endpoints to which the message was sent. Use this field to get more informative errors. Provide the same value as the send_message has returned. If the message was not delivered (expired), SDK will log the endpoint URLs, used for its sending.
  • responseHandler?: ResponseHandler – additional responses handler.

Result

  • transaction: any – Parsed transaction. In addition to the regular transaction fields there is a boc field encoded with base64 which contains source transaction BOC.
  • out_messages: string[] – List of output messages' BOCs. Encoded as base64
  • decoded?: DecodedOutput – Optional decoded message bodies according to the optional abi parameter.
  • fees: TransactionFees – Transaction fees

process_message

Creates message, sends it to the network and monitors its processing.
Creates ABI-compatible message, sends it to the network and monitors for the result transaction. Decodes the output messages' bodies.
If contract's ABI includes "expire" header, then SDK implements retries in case of unsuccessful message delivery within the expiration timeout: SDK recreates the message, sends it and processes it again.
The intermediate events, such as WillFetchFirstBlock, WillSend, DidSend, WillFetchNextBlock, etc - are switched on/off by send_events flag and logged into the supplied callback function.
The retry configuration parameters are defined in the client's NetworkConfig and AbiConfig.
If contract's ABI does not include "expire" header then, if no transaction is found within the network timeout (see config parameter ), exits with error.
type ParamsOfProcessMessage = {
message_encode_params: ParamsOfEncodeMessage,
send_events?: boolean
}
type ResultOfProcessMessage = {
transaction: any,
out_messages: string[],
decoded?: DecodedOutput,
fees: TransactionFees
}
function process_message(
params: ParamsOfProcessMessage,
responseHandler?: ResponseHandler,
): Promise<ResultOfProcessMessage>;
function process_message_sync(
params: ParamsOfProcessMessage,
): ResultOfProcessMessage;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • message_encode_params: ParamsOfEncodeMessage – Message encode parameters.
  • send_events?: boolean – Flag for requesting events sending. Default is false.
  • responseHandler?: ResponseHandler – additional responses handler.

Result

  • transaction: any – Parsed transaction. In addition to the regular transaction fields there is a boc field encoded with base64 which contains source transaction BOC.
  • out_messages: string[] – List of output messages' BOCs. Encoded as base64
  • decoded?: DecodedOutput – Optional decoded message bodies according to the optional abi parameter.
  • fees: TransactionFees – Transaction fees

Types

ProcessingErrorCode

enum ProcessingErrorCode {
MessageAlreadyExpired = 501,
MessageHasNotDestinationAddress = 502,
CanNotBuildMessageCell = 503,
FetchBlockFailed = 504,
SendMessageFailed = 505,
InvalidMessageBoc = 506,
MessageExpired = 507,
TransactionWaitTimeout = 508,
InvalidBlockReceived = 509,
CanNotCheckBlockShard = 510,
BlockNotFound = 511,
InvalidData = 512,
ExternalSignerMustNotBeUsed = 513,
MessageRejected = 514,
InvalidRempStatus = 515,
NextRempStatusTimeout = 516
}
One of the following value:
  • MessageAlreadyExpired = 501
  • MessageHasNotDestinationAddress = 502
  • CanNotBuildMessageCell = 503
  • FetchBlockFailed = 504
  • SendMessageFailed = 505
  • InvalidMessageBoc = 506
  • MessageExpired = 507
  • TransactionWaitTimeout = 508
  • InvalidBlockReceived = 509
  • CanNotCheckBlockShard = 510
  • BlockNotFound = 511
  • InvalidData = 512
  • ExternalSignerMustNotBeUsed = 513
  • MessageRejected = 514
  • InvalidRempStatus = 515
  • NextRempStatusTimeout = 516

ProcessingEventWillFetchFirstBlockVariant

Notifies the application that the account's current shard block will be fetched from the network. This step is performed before the message sending so that sdk knows starting from which block it will search for the transaction.
Fetched block will be used later in waiting phase.
type ProcessingEventWillFetchFirstBlockVariant = {
message_id: string,
message_dst: string
}
  • message_id: string
  • message_dst: string

ProcessingEventFetchFirstBlockFailedVariant

Notifies the app that the client has failed to fetch the account's current shard block.
This may happen due to the network issues. Receiving this event means that message processing will not proceed - message was not sent, and Developer can try to run process_message again, in the hope that the connection is restored.
type ProcessingEventFetchFirstBlockFailedVariant = {
error: ClientError,
message_id: string,
message_dst: string
}
  • error: ClientError
  • message_id: string
  • message_dst: string

ProcessingEventWillSendVariant

Notifies the app that the message will be sent to the network. This event means that the account's current shard block was successfully fetched and the message was successfully created (abi.encode_message function was executed successfully).
type ProcessingEventWillSendVariant = {
shard_block_id: string,
message_id: string,
message_dst: string,
message: string
}
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string

ProcessingEventDidSendVariant

Notifies the app that the message was sent to the network, i.e processing.send_message was successfully executed. Now, the message is in the blockchain. If Application exits at this phase, Developer needs to proceed with processing after the application is restored with wait_for_transaction function, passing shard_block_id and message from this event.
Do not forget to specify abi of your contract as well, it is crucial for processing. See processing.wait_for_transaction documentation.
type ProcessingEventDidSendVariant = {
shard_block_id: string,
message_id: string,
message_dst: string,
message: string
}
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string

ProcessingEventSendFailedVariant

Notifies the app that the sending operation was failed with network error.
Nevertheless the processing will be continued at the waiting phase because the message possibly has been delivered to the node. If Application exits at this phase, Developer needs to proceed with processing after the application is restored with wait_for_transaction function, passing shard_block_id and message from this event. Do not forget to specify abi of your contract as well, it is crucial for processing. See processing.wait_for_transaction documentation.
type ProcessingEventSendFailedVariant = {
shard_block_id: string,
message_id: string,
message_dst: string,
message: string,
error: ClientError
}
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string
  • error: ClientError

ProcessingEventWillFetchNextBlockVariant

Notifies the app that the next shard block will be fetched from the network.
Event can occurs more than one time due to block walking procedure. If Application exits at this phase, Developer needs to proceed with processing after the application is restored with wait_for_transaction function, passing shard_block_id and message from this event. Do not forget to specify abi of your contract as well, it is crucial for processing. See processing.wait_for_transaction documentation.
type ProcessingEventWillFetchNextBlockVariant = {
shard_block_id: string,
message_id: string,
message_dst: string,
message: string
}
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string

ProcessingEventFetchNextBlockFailedVariant

Notifies the app that the next block can't be fetched.
If no block was fetched within NetworkConfig.wait_for_timeout then processing stops. This may happen when the shard stops, or there are other network issues. In this case Developer should resume message processing with wait_for_transaction, passing shard_block_id, message and contract abi to it. Note that passing ABI is crucial, because it will influence the processing strategy.
Another way to tune this is to specify long timeout in NetworkConfig.wait_for_timeout
type ProcessingEventFetchNextBlockFailedVariant = {
shard_block_id: string,
message_id: string,
message_dst: string,
message: string,
error: ClientError
}
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string
  • error: ClientError

ProcessingEventMessageExpiredVariant

Notifies the app that the message was not executed within expire timeout on-chain and will never be because it is already expired. The expiration timeout can be configured with AbiConfig parameters.
This event occurs only for the contracts which ABI includes "expire" header.
If Application specifies NetworkConfig.message_retries_count > 0, then process_message will perform retries: will create a new message and send it again and repeat it until it reaches the maximum retries count or receives a successful result. All the processing events will be repeated.
type ProcessingEventMessageExpiredVariant = {
message_id: string,
message_dst: string,
message: string,
error: ClientError
}
  • message_id: string
  • message_dst: string
  • message: string
  • error: ClientError

ProcessingEventRempSentToValidatorsVariant

Notifies the app that the message has been delivered to the thread's validators
type ProcessingEventRempSentToValidatorsVariant = {
message_id: string,
message_dst: string,
timestamp: bigint,
json: any
}
  • message_id: string
  • message_dst: string
  • timestamp: bigint
  • json: any

ProcessingEventRempIncludedIntoBlockVariant

Notifies the app that the message has been successfully included into a block candidate by the thread's collator
type ProcessingEventRempIncludedIntoBlockVariant = {
message_id: string,
message_dst: string,
timestamp: bigint,
json: any
}
  • message_id: string
  • message_dst: string
  • timestamp: bigint
  • json: any

ProcessingEventRempIncludedIntoAcceptedBlockVariant

Notifies the app that the block candidate with the message has been accepted by the thread's validators
type ProcessingEventRempIncludedIntoAcceptedBlockVariant = {
message_id: string,
message_dst: string,
timestamp: bigint,
json: any
}
  • message_id: string
  • message_dst: string
  • timestamp: bigint
  • json: any

ProcessingEventRempOtherVariant

Notifies the app about some other minor REMP statuses occurring during message processing
type ProcessingEventRempOtherVariant = {
message_id: string,
message_dst: string,
timestamp: bigint,
json: any
}
  • message_id: string
  • message_dst: string
  • timestamp: bigint
  • json: any

ProcessingEventRempErrorVariant

Notifies the app about any problem that has occurred in REMP processing - in this case library switches to the fallback transaction awaiting scenario (sequential block reading).
type ProcessingEventRempErrorVariant = {
message_id: string,
message_dst: string,
error: ClientError
}
  • message_id: string
  • message_dst: string
  • error: ClientError

ProcessingEvent

type ProcessingEvent = ({
type: 'WillFetchFirstBlock'
} & ProcessingEventWillFetchFirstBlockVariant) | ({
type: 'FetchFirstBlockFailed'
} & ProcessingEventFetchFirstBlockFailedVariant) | ({
type: 'WillSend'
} & ProcessingEventWillSendVariant) | ({
type: 'DidSend'
} & ProcessingEventDidSendVariant) | ({
type: 'SendFailed'
} & ProcessingEventSendFailedVariant) | ({
type: 'WillFetchNextBlock'
} & ProcessingEventWillFetchNextBlockVariant) | ({
type: 'FetchNextBlockFailed'
} & ProcessingEventFetchNextBlockFailedVariant) | ({
type: 'MessageExpired'
} & ProcessingEventMessageExpiredVariant) | ({
type: 'RempSentToValidators'
} & ProcessingEventRempSentToValidatorsVariant) | ({
type: 'RempIncludedIntoBlock'
} & ProcessingEventRempIncludedIntoBlockVariant) | ({
type: 'RempIncludedIntoAcceptedBlock'
} & ProcessingEventRempIncludedIntoAcceptedBlockVariant) | ({
type: 'RempOther'
} & ProcessingEventRempOtherVariant) | ({
type: 'RempError'
} & ProcessingEventRempErrorVariant)
Depends on value of the type field.
When type is 'WillFetchFirstBlock'
Notifies the application that the account's current shard block will be fetched from the network. This step is performed before the message sending so that sdk knows starting from which block it will search for the transaction.
Fetched block will be used later in waiting phase.
  • message_id: string
  • message_dst: string
When type is 'FetchFirstBlockFailed'
Notifies the app that the client has failed to fetch the account's current shard block.
This may happen due to the network issues. Receiving this event means that message processing will not proceed - message was not sent, and Developer can try to run process_message again, in the hope that the connection is restored.
  • error: ClientError
  • message_id: string
  • message_dst: string
When type is 'WillSend'
Notifies the app that the message will be sent to the network. This event means that the account's current shard block was successfully fetched and the message was successfully created (abi.encode_message function was executed successfully).
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string
When type is 'DidSend'
Notifies the app that the message was sent to the network, i.e processing.send_message was successfully executed. Now, the message is in the blockchain. If Application exits at this phase, Developer needs to proceed with processing after the application is restored with wait_for_transaction function, passing shard_block_id and message from this event.
Do not forget to specify abi of your contract as well, it is crucial for processing. See processing.wait_for_transaction documentation.
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string
When type is 'SendFailed'
Notifies the app that the sending operation was failed with network error.
Nevertheless the processing will be continued at the waiting phase because the message possibly has been delivered to the node. If Application exits at this phase, Developer needs to proceed with processing after the application is restored with wait_for_transaction function, passing shard_block_id and message from this event. Do not forget to specify abi of your contract as well, it is crucial for processing. See processing.wait_for_transaction documentation.
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string
  • error: ClientError
When type is 'WillFetchNextBlock'
Notifies the app that the next shard block will be fetched from the network.
Event can occurs more than one time due to block walking procedure. If Application exits at this phase, Developer needs to proceed with processing after the application is restored with wait_for_transaction function, passing shard_block_id and message from this event. Do not forget to specify abi of your contract as well, it is crucial for processing. See processing.wait_for_transaction documentation.
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string
When type is 'FetchNextBlockFailed'
Notifies the app that the next block can't be fetched.
If no block was fetched within NetworkConfig.wait_for_timeout then processing stops. This may happen when the shard stops, or there are other network issues. In this case Developer should resume message processing with wait_for_transaction, passing shard_block_id, message and contract abi to it. Note that passing ABI is crucial, because it will influence the processing strategy.
Another way to tune this is to specify long timeout in NetworkConfig.wait_for_timeout
  • shard_block_id: string
  • message_id: string
  • message_dst: string
  • message: string
  • error: ClientError
When type is 'MessageExpired'
Notifies the app that the message was not executed within expire timeout on-chain and will never be because it is already expired. The expiration timeout can be configured with AbiConfig parameters.
This event occurs only for the contracts which ABI includes "expire" header.
If Application specifies NetworkConfig.message_retries_count > 0, then process_message will perform retries: will create a new message and send it again and repeat it until it reaches the maximum retries count or receives a successful result. All the processing events will be repeated.
  • message_id: string
  • message_dst: string
  • message: string
  • error: ClientError
When type is 'RempSentToValidators'
Notifies the app that the message has been delivered to the thread's validators
  • message_id: string
  • message_dst: string
  • timestamp: bigint
  • json: any
When type is 'RempIncludedIntoBlock'
Notifies the app that the message has been successfully included into a block candidate by the thread's collator
  • message_id: string
  • message_dst: string
  • timestamp: bigint
  • json: any
When type is 'RempIncludedIntoAcceptedBlock'
Notifies the app that the block candidate with the message has been accepted by the thread's validators
  • message_id: string
  • message_dst: string