Skip to content

Latest commit

 

History

History
441 lines (335 loc) · 13.8 KB

mod_processing.md

File metadata and controls

441 lines (335 loc) · 13.8 KB
Raw

Module processing

Message processing module.

This module incorporates functions related to complex message processing scenarios.

Functions

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

ProcessingErrorCode

ProcessingEvent

ResultOfProcessMessage

DecodedOutput

ParamsOfSendMessage

ResultOfSendMessage

ParamsOfWaitForTransaction

ParamsOfProcessMessage

Functions

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
}

function send_message(
    params: ParamsOfSendMessage,
    responseHandler?: ResponseHandler,
): Promise<ResultOfSendMessage>;

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
  • 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.

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
}

type ResultOfProcessMessage = {
    transaction: any,
    out_messages: string[],
    decoded?: DecodedOutput,
    fees: TransactionFees
}

function wait_for_transaction(
    params: ParamsOfWaitForTransaction,
    responseHandler?: ResponseHandler,
): Promise<ResultOfProcessMessage>;

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
  • 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>;

Parameters

  • message_encode_params: ParamsOfEncodeMessage – Message encode parameters.
  • send_events: boolean – Flag for requesting events 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

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
}

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

ProcessingEvent

type ProcessingEvent = {
    type: 'WillFetchFirstBlock'
} | {
    type: 'FetchFirstBlockFailed'
    error: ClientError
} | {
    type: 'WillSend'
    shard_block_id: string,
    message_id: string,
    message: string
} | {
    type: 'DidSend'
    shard_block_id: string,
    message_id: string,
    message: string
} | {
    type: 'SendFailed'
    shard_block_id: string,
    message_id: string,
    message: string,
    error: ClientError
} | {
    type: 'WillFetchNextBlock'
    shard_block_id: string,
    message_id: string,
    message: string
} | {
    type: 'FetchNextBlockFailed'
    shard_block_id: string,
    message_id: string,
    message: string,
    error: ClientError
} | {
    type: 'MessageExpired'
    message_id: string,
    message: string,
    error: ClientError
}

Depends on value of the type field.

When type is 'WillFetchFirstBlock'

Notifies the app that the current shard block will be fetched from the network.

Fetched block will be used later in waiting phase.

When type is 'FetchFirstBlockFailed'

Notifies the app that the client has failed to fetch current shard block.

Message processing has finished.

When type is 'WillSend'

Notifies the app that the message will be sent to the network.

  • shard_block_id: string
  • message_id: string
  • message: string

When type is 'DidSend'

Notifies the app that the message was sent to the network.

  • shard_block_id: string
  • message_id: 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.

  • shard_block_id: string
  • message_id: 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.

  • shard_block_id: string
  • message_id: string
  • message: string

When type is 'FetchNextBlockFailed'

Notifies the app that the next block can't be fetched due to error.

Processing will be continued after network_resume_timeout.

  • shard_block_id: string
  • message_id: string
  • message: string
  • error: ClientError

When type is 'MessageExpired'

Notifies the app that the message was expired.

Event occurs for contracts which ABI includes header "expire"

Processing will be continued from encoding phase after expiration_retries_timeout.

  • message_id: string
  • message: string
  • error: ClientError

ResultOfProcessMessage

type ResultOfProcessMessage = {
    transaction: any,
    out_messages: string[],
    decoded?: DecodedOutput,
    fees: TransactionFees
}
  • 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

DecodedOutput

type DecodedOutput = {
    out_messages: DecodedMessageBody | null[],
    output?: any
}
  • out_messages: DecodedMessageBody?[] – Decoded bodies of the out messages.
    If the message can't be decoded, then None will be stored in
    the appropriate position.
  • output?: any – Decoded body of the function output message.

ParamsOfSendMessage

type ParamsOfSendMessage = {
    message: string,
    abi?: Abi,
    send_events: boolean
}
  • 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

ResultOfSendMessage

type ResultOfSendMessage = {
    shard_block_id: string
}
  • 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.

ParamsOfWaitForTransaction

type ParamsOfWaitForTransaction = {
    abi?: Abi,
    message: string,
    shard_block_id: string,
    send_events: boolean
}
  • 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

ParamsOfProcessMessage

type ParamsOfProcessMessage = {
    message_encode_params: ParamsOfEncodeMessage,
    send_events: boolean
}
  • message_encode_params: ParamsOfEncodeMessage – Message encode parameters.
  • send_events: boolean – Flag for requesting events sending