EVER SDK
Developer ToolsEver PlatformForum
Search
⌃K
Links

Module abi

Module abi

Provides message encoding and decoding according to the ABI specification.

Functions

​encode_message_body – Encodes message body according to ABI function call.
​encode_message – Encodes an ABI-compatible message
​encode_internal_message – Encodes an internal ABI-compatible message
​attach_signature – Combines hex-encoded signature with base64-encoded unsigned_message. Returns signed message encoded in base64.
​decode_message – Decodes message body using provided message BOC and ABI.
​decode_message_body – Decodes message body using provided body BOC and ABI.
​encode_account – Creates account state BOC
​decode_account_data – Decodes account data using provided data BOC and ABI.
​update_initial_data – Updates initial account data with initial values for the contract's static variables and owner's public key. This operation is applicable only for initial account data (before deploy). If the contract is already deployed, its data doesn't contain this data section any more.
​encode_initial_data – Encodes initial account data with initial values for the contract's static variables and owner's public key into a data BOC that can be passed to encode_tvc function afterwards.
​decode_initial_data – Decodes initial values of a contract's static variables and owner's public key from account initial data This operation is applicable only for initial account data (before deploy). If the contract is already deployed, its data doesn't contain this data section any more.
​decode_boc – Decodes BOC into JSON as a set of provided parameters.
​encode_boc – Encodes given parameters in JSON into a BOC using param types from ABI.
​calc_function_id – Calculates contract function ID by contract ABI
​get_signature_data – Extracts signature from message body and calculates hash to verify the signature

Types

​Abi​
​AbiHandle​
​FunctionHeader – The ABI function header.
​CallSet​
​DeploySet​
​SignerNoneVariant – No keys are provided.
​SignerExternalVariant – Only public key is provided in unprefixed hex string format to generate unsigned message and data_to_sign which can be signed later.
​SignerKeysVariant – Key pair is provided for signing
​SignerSigningBoxVariant – Signing Box interface is provided for signing, allows Dapps to sign messages using external APIs, such as HSM, cold wallet, etc.
​Signer​
​StateInitSourceMessageVariant – Deploy message.
​StateInitSourceStateInitVariant – State init data.
​StateInitSourceTvcVariant – Content of the TVC file.
​AbiParam​
​AbiEvent​
​AbiData​

Functions

encode_message_body

Encodes message body according to ABI function call.
type ParamsOfEncodeMessageBody = {
abi: Abi,
call_set: CallSet,
is_internal: boolean,
signer: Signer,
processing_try_index?: number,
address?: string,
signature_id?: number
}
​
type ResultOfEncodeMessageBody = {
body: string,
data_to_sign?: string
}
​
function encode_message_body(
params: ParamsOfEncodeMessageBody,
): Promise<ResultOfEncodeMessageBody>;
​
function encode_message_body_sync(
params: ParamsOfEncodeMessageBody,
): ResultOfEncodeMessageBody;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI.
  • call_set: CallSet – Function call parameters. Must be specified in non deploy message. In case of deploy message contains parameters of constructor.
  • is_internal: boolean – True if internal message body must be encoded.
  • signer: Signer – Signing parameters.
  • processing_try_index?: number – Processing try index. Used in message processing with retries. Encoder uses the provided try index to calculate message expiration time. Expiration timeouts will grow with every retry. Default value is 0.
  • address?: string – Destination address of the message Since ABI version 2.3 destination address of external inbound message is used in message body signature calculation. Should be provided when signed external inbound message body is created. Otherwise can be omitted.
  • signature_id?: number – Signature ID to be used in data to sign preparing when CapSignatureWithId capability is enabled

Result

  • body: string – Message body BOC encoded with base64.
  • data_to_sign?: string – Optional data to sign. Encoded with base64. Presents when message is unsigned. Can be used for external message signing. Is this case you need to sing this data and produce signed message using abi.attach_signature.

attach_signature_to_message_body

type ParamsOfAttachSignatureToMessageBody = {
abi: Abi,
public_key: string,
message: string,
signature: string
}
​
type ResultOfAttachSignatureToMessageBody = {
body: string
}
​
function attach_signature_to_message_body(
params: ParamsOfAttachSignatureToMessageBody,
): Promise<ResultOfAttachSignatureToMessageBody>;
​
function attach_signature_to_message_body_sync(
params: ParamsOfAttachSignatureToMessageBody,
): ResultOfAttachSignatureToMessageBody;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI
  • public_key: string – Public key. Must be encoded with hex.
  • message: string – Unsigned message body BOC. Must be encoded with base64.
  • signature: string – Signature. Must be encoded with hex.

Result

  • body: string

encode_message

Encodes an ABI-compatible message
Allows to encode deploy and function call messages, both signed and unsigned.
Use cases include messages of any possible type:
  • deploy with initial function call (i.e. constructor or any other function that is used for some kind of initialization);
  • deploy without initial function call;
  • signed/unsigned + data for signing.
Signer defines how the message should or shouldn't be signed:
Signer::None creates an unsigned message. This may be needed in case of some public methods, that do not require authorization by pubkey.
Signer::External takes public key and returns data_to_sign for later signing. Use attach_signature method with the result signature to get the signed message.
Signer::Keys creates a signed message with provided key pair.
[SOON] Signer::SigningBox Allows using a special interface to implement signing without private key disclosure to SDK. For instance, in case of using a cold wallet or HSM, when application calls some API to sign data.
There is an optional public key can be provided in deploy set in order to substitute one in TVM file.
Public key resolving priority:
  1. 1.
    Public key from deploy set.
  2. 2.
    Public key, specified in TVM file.
  3. 3.
    Public key, provided by signer.
type ParamsOfEncodeMessage = {
abi: Abi,
address?: string,
deploy_set?: DeploySet,
call_set?: CallSet,
signer: Signer,
processing_try_index?: number,
signature_id?: number
}
​
type ResultOfEncodeMessage = {
message: string,
data_to_sign?: string,
address: string,
message_id: string
}
​
function encode_message(
params: ParamsOfEncodeMessage,
): Promise<ResultOfEncodeMessage>;
​
function encode_message_sync(
params: ParamsOfEncodeMessage,
): ResultOfEncodeMessage;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI.
  • address?: string – Target address the message will be sent to. Must be specified in case of non-deploy message.
  • deploy_set?: DeploySet – Deploy parameters. Must be specified in case of deploy message.
  • call_set?: CallSet – Function call parameters. Must be specified in case of non-deploy message. In case of deploy message it is optional and contains parameters of the functions that will to be called upon deploy transaction.
  • signer: Signer – Signing parameters.
  • processing_try_index?: number – Processing try index. Used in message processing with retries (if contract's ABI includes "expire" header). Encoder uses the provided try index to calculate message expiration time. The 1st message expiration time is specified in Client config. Expiration timeouts will grow with every retry. Retry grow factor is set in Client config: <.....add config parameter with default value here> Default value is 0.
  • signature_id?: number – Signature ID to be used in data to sign preparing when CapSignatureWithId capability is enabled

Result

  • message: string – Message BOC encoded with base64.
  • data_to_sign?: string – Optional data to be signed encoded in base64. Returned in case of Signer::External. Can be used for external message signing. Is this case you need to use this data to create signature and then produce signed message using abi.attach_signature.
  • address: string – Destination address.
  • message_id: string – Message id.

encode_internal_message

Encodes an internal ABI-compatible message
Allows to encode deploy and function call messages.
Use cases include messages of any possible type:
  • deploy with initial function call (i.e. constructor or any other function that is used for some kind of initialization);
  • deploy without initial function call;
  • simple function call
There is an optional public key can be provided in deploy set in order to substitute one in TVM file.
Public key resolving priority:
  1. 1.
    Public key from deploy set.
  2. 2.
    Public key, specified in TVM file.
type ParamsOfEncodeInternalMessage = {
abi?: Abi,
address?: string,
src_address?: string,
deploy_set?: DeploySet,
call_set?: CallSet,
value: string,
bounce?: boolean,
enable_ihr?: boolean
}
​
type ResultOfEncodeInternalMessage = {
message: string,
address: string,
message_id: string
}
​
function encode_internal_message(
params: ParamsOfEncodeInternalMessage,
): Promise<ResultOfEncodeInternalMessage>;
​
function encode_internal_message_sync(
params: ParamsOfEncodeInternalMessage,
): ResultOfEncodeInternalMessage;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi?: Abi – Contract ABI. Can be None if both deploy_set and call_set are None.
  • address?: string – Target address the message will be sent to. Must be specified in case of non-deploy message.
  • src_address?: string – Source address of the message.
  • deploy_set?: DeploySet – Deploy parameters. Must be specified in case of deploy message.
  • call_set?: CallSet – Function call parameters. Must be specified in case of non-deploy message. In case of deploy message it is optional and contains parameters of the functions that will to be called upon deploy transaction.
  • value: string – Value in nanotokens to be sent with message.
  • bounce?: boolean – Flag of bounceable message. Default is true.
  • enable_ihr?: boolean – Enable Instant Hypercube Routing for the message. Default is false.

Result

  • message: string – Message BOC encoded with base64.
  • address: string – Destination address.
  • message_id: string – Message id.

attach_signature

Combines hex-encoded signature with base64-encoded unsigned_message. Returns signed message encoded in base64.
type ParamsOfAttachSignature = {
abi: Abi,
public_key: string,
message: string,
signature: string
}
​
type ResultOfAttachSignature = {
message: string,
message_id: string
}
​
function attach_signature(
params: ParamsOfAttachSignature,
): Promise<ResultOfAttachSignature>;
​
function attach_signature_sync(
params: ParamsOfAttachSignature,
): ResultOfAttachSignature;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI
  • public_key: string – Public key encoded in hex.
  • message: string – Unsigned message BOC encoded in base64.
  • signature: string – Signature encoded in hex.

Result

  • message: string – Signed message BOC
  • message_id: string – Message ID

decode_message

Decodes message body using provided message BOC and ABI.
type ParamsOfDecodeMessage = {
abi: Abi,
message: string,
allow_partial?: boolean,
function_name?: string,
data_layout?: DataLayout
}
​
type DecodedMessageBody = {
body_type: MessageBodyType,
name: string,
value?: any,
header?: FunctionHeader
}
​
function decode_message(
params: ParamsOfDecodeMessage,
): Promise<DecodedMessageBody>;
​
function decode_message_sync(
params: ParamsOfDecodeMessage,
): DecodedMessageBody;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – contract ABI
  • message: string – Message BOC
  • allow_partial?: boolean – Flag allowing partial BOC decoding when ABI doesn't describe the full body BOC. Controls decoder behaviour when after decoding all described in ABI params there are some data left in BOC: true - return decoded values false - return error of incomplete BOC deserialization (default)
  • function_name?: string – Function name or function id if is known in advance
  • data_layout?: DataLayout​

Result

  • body_type: MessageBodyType – Type of the message body content.
  • name: string – Function or event name.
  • value?: any – Parameters or result value.
  • header?: FunctionHeader – Function header.

decode_message_body

Decodes message body using provided body BOC and ABI.
type ParamsOfDecodeMessageBody = {
abi: Abi,
body: string,
is_internal: boolean,
allow_partial?: boolean,
function_name?: string,
data_layout?: DataLayout
}
​
type DecodedMessageBody = {
body_type: MessageBodyType,
name: string,
value?: any,
header?: FunctionHeader
}
​
function decode_message_body(
params: ParamsOfDecodeMessageBody,
): Promise<DecodedMessageBody>;
​
function decode_message_body_sync(
params: ParamsOfDecodeMessageBody,
): DecodedMessageBody;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI used to decode.
  • body: string – Message body BOC encoded in base64.
  • is_internal: boolean – True if the body belongs to the internal message.
  • allow_partial?: boolean – Flag allowing partial BOC decoding when ABI doesn't describe the full body BOC. Controls decoder behaviour when after decoding all described in ABI params there are some data left in BOC: true - return decoded values false - return error of incomplete BOC deserialization (default)
  • function_name?: string – Function name or function id if is known in advance
  • data_layout?: DataLayout​

Result

  • body_type: MessageBodyType – Type of the message body content.
  • name: string – Function or event name.
  • value?: any – Parameters or result value.
  • header?: FunctionHeader – Function header.

encode_account

Creates account state BOC
Creates account state provided with one of these sets of data :
  1. 1.
    BOC of code, BOC of data, BOC of library
  2. 2.
    TVC (string in base64), keys, init params
type ParamsOfEncodeAccount = {
state_init: StateInitSource,
balance?: bigint,
last_trans_lt?: bigint,
last_paid?: number,
boc_cache?: BocCacheType
}
​
type ResultOfEncodeAccount = {
account: string,
id: string
}
​
function encode_account(
params: ParamsOfEncodeAccount,
): Promise<ResultOfEncodeAccount>;
​
function encode_account_sync(
params: ParamsOfEncodeAccount,
): ResultOfEncodeAccount;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • state_init: StateInitSource – Source of the account state init.
  • balance?: bigint – Initial balance.
  • last_trans_lt?: bigint – Initial value for the last_trans_lt.
  • last_paid?: number – Initial value for the last_paid.
  • boc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type provided

Result

  • account: string – Account BOC encoded in base64.
  • id: string – Account ID encoded in hex.

decode_account_data

Decodes account data using provided data BOC and ABI.
Note: this feature requires ABI 2.1 or higher.
type ParamsOfDecodeAccountData = {
abi: Abi,
data: string,
allow_partial?: boolean
}
​
type ResultOfDecodeAccountData = {
data: any
}
​
function decode_account_data(
params: ParamsOfDecodeAccountData,
): Promise<ResultOfDecodeAccountData>;
​
function decode_account_data_sync(
params: ParamsOfDecodeAccountData,
): ResultOfDecodeAccountData;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI
  • data: string – Data BOC or BOC handle
  • allow_partial?: boolean – Flag allowing partial BOC decoding when ABI doesn't describe the full body BOC. Controls decoder behaviour when after decoding all described in ABI params there are some data left in BOC: true - return decoded values false - return error of incomplete BOC deserialization (default)

Result

  • data: any – Decoded data as a JSON structure.

update_initial_data

Updates initial account data with initial values for the contract's static variables and owner's public key. This operation is applicable only for initial account data (before deploy). If the contract is already deployed, its data doesn't contain this data section any more.
type ParamsOfUpdateInitialData = {
abi?: Abi,
data: string,
initial_data?: any,
initial_pubkey?: string,
boc_cache?: BocCacheType
}
​
type ResultOfUpdateInitialData = {
data: string
}
​
function update_initial_data(
params: ParamsOfUpdateInitialData,
): Promise<ResultOfUpdateInitialData>;
​
function update_initial_data_sync(
params: ParamsOfUpdateInitialData,
): ResultOfUpdateInitialData;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi?: Abi – Contract ABI
  • data: string – Data BOC or BOC handle
  • initial_data?: any – List of initial values for contract's static variables. abi parameter should be provided to set initial data
  • initial_pubkey?: string – Initial account owner's public key to set into account data
  • boc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type provided.

Result

  • data: string – Updated data BOC or BOC handle

encode_initial_data

Encodes initial account data with initial values for the contract's static variables and owner's public key into a data BOC that can be passed to encode_tvc function afterwards.
This function is analogue of tvm.buildDataInit function in Solidity.
type ParamsOfEncodeInitialData = {
abi?: Abi,
initial_data?: any,
initial_pubkey?: string,
boc_cache?: BocCacheType
}
​
type ResultOfEncodeInitialData = {
data: string
}
​
function encode_initial_data(
params: ParamsOfEncodeInitialData,
): Promise<ResultOfEncodeInitialData>;
​
function encode_initial_data_sync(
params: ParamsOfEncodeInitialData,
): ResultOfEncodeInitialData;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi?: Abi – Contract ABI
  • initial_data?: any – List of initial values for contract's static variables. abi parameter should be provided to set initial data
  • initial_pubkey?: string – Initial account owner's public key to set into account data
  • boc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type provided.

Result

  • data: string – Updated data BOC or BOC handle

decode_initial_data

Decodes initial values of a contract's static variables and owner's public key from account initial data This operation is applicable only for initial account data (before deploy). If the contract is already deployed, its data doesn't contain this data section any more.
type ParamsOfDecodeInitialData = {
abi?: Abi,
data: string,
allow_partial?: boolean
}
​
type ResultOfDecodeInitialData = {
initial_data?: any,
initial_pubkey: string
}
​
function decode_initial_data(
params: ParamsOfDecodeInitialData,
): Promise<ResultOfDecodeInitialData>;
​
function decode_initial_data_sync(
params: ParamsOfDecodeInitialData,
): ResultOfDecodeInitialData;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi?: Abi – Contract ABI. Initial data is decoded if this parameter is provided
  • data: string – Data BOC or BOC handle
  • allow_partial?: boolean – Flag allowing partial BOC decoding when ABI doesn't describe the full body BOC. Controls decoder behaviour when after decoding all described in ABI params there are some data left in BOC: true - return decoded values false - return error of incomplete BOC deserialization (default)

Result

  • initial_data?: any – List of initial values of contract's public variables. Initial data is decoded if abi input parameter is provided
  • initial_pubkey: string – Initial account owner's public key

decode_boc

Decodes BOC into JSON as a set of provided parameters.
Solidity functions use ABI types for builder encoding. The simplest way to decode such a BOC is to use ABI decoding. ABI has it own rules for fields layout in cells so manually encoded BOC can not be described in terms of ABI rules.
To solve this problem we introduce a new ABI type Ref(<ParamType>) which allows to store ParamType ABI parameter in cell reference and, thus, decode manually encoded BOCs. This type is available only in decode_boc function and will not be available in ABI messages encoding until it is included into some ABI revision.
Such BOC descriptions covers most users needs. If someone wants to decode some BOC which can not be described by these rules (i.e. BOC with TLB containing constructors of flags defining some parsing conditions) then they can decode the fields up to fork condition, check the parsed data manually, expand the parsing schema and then decode the whole BOC with the full schema.
type ParamsOfDecodeBoc = {
params: AbiParam[],
boc: string,
allow_partial: boolean
}
​
type ResultOfDecodeBoc = {
data: any
}
​
function decode_boc(
params: ParamsOfDecodeBoc,
): Promise<ResultOfDecodeBoc>;
​
function decode_boc_sync(
params: ParamsOfDecodeBoc,
): ResultOfDecodeBoc;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • params: AbiParam[] – Parameters to decode from BOC
  • boc: string – Data BOC or BOC handle
  • allow_partial: boolean

Result

  • data: any – Decoded data as a JSON structure.

encode_boc

Encodes given parameters in JSON into a BOC using param types from ABI.
type ParamsOfAbiEncodeBoc = {
params: AbiParam[],
data: any,
boc_cache?: BocCacheType
}
​
type ResultOfAbiEncodeBoc = {
boc: string
}
​
function encode_boc(
params: ParamsOfAbiEncodeBoc,
): Promise<ResultOfAbiEncodeBoc>;
​
function encode_boc_sync(
params: ParamsOfAbiEncodeBoc,
): ResultOfAbiEncodeBoc;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • params: AbiParam[] – Parameters to encode into BOC
  • data: any – Parameters and values as a JSON structure
  • boc_cache?: BocCacheType – Cache type to put the result. The BOC itself returned if no cache type provided

Result

  • boc: string – BOC encoded as base64

calc_function_id

Calculates contract function ID by contract ABI
type ParamsOfCalcFunctionId = {
abi: Abi,
function_name: string,
output?: boolean
}
​
type ResultOfCalcFunctionId = {
function_id: number
}
​
function calc_function_id(
params: ParamsOfCalcFunctionId,
): Promise<ResultOfCalcFunctionId>;
​
function calc_function_id_sync(
params: ParamsOfCalcFunctionId,
): ResultOfCalcFunctionId;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI.
  • function_name: string – Contract function name
  • output?: boolean – If set to true output function ID will be returned which is used in contract response. Default is false

Result

  • function_id: number – Contract function ID

get_signature_data

Extracts signature from message body and calculates hash to verify the signature
type ParamsOfGetSignatureData = {
abi: Abi,
message: string,
signature_id?: number
}
​
type ResultOfGetSignatureData = {
signature: string,
unsigned: string
}
​
function get_signature_data(
params: ParamsOfGetSignatureData,
): Promise<ResultOfGetSignatureData>;
​
function get_signature_data_sync(
params: ParamsOfGetSignatureData,
): ResultOfGetSignatureData;
NOTE: Sync version is available only for lib-node binding.

Parameters

  • abi: Abi – Contract ABI used to decode.
  • message: string – Message BOC encoded in base64.
  • signature_id?: number – Signature ID to be used in unsigned data preparing when CapSignatureWithId capability is enabled

Result

  • signature: string – Signature from the message in hex.
  • unsigned: string – Data to verify the signature in base64.

Types

AbiErrorCode