Module java4ever.binding

Package tech.deplant.java4ever.binding

Class Abi

java.lang.Object

tech.deplant.java4ever.binding.Abi

public final class Abi
extends Object

Abi Contains methods of "abi" module of EVER-SDK API

Provides message encoding and decoding according to the ABI specification.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	Abi.ABI
static final record	Abi.AbiContract
static final record	Abi.AbiData
static enum	Abi.AbiErrorCode
static final record	Abi.AbiEvent
static final record	Abi.AbiFunction
static final record	Abi.AbiParam
static final record	Abi.CallSet
static enum	Abi.DataLayout
static final record	Abi.DecodedMessageBody
static final record	Abi.DeploySet
static final record	Abi.FunctionHeader	Includes several hidden function parameters that contract uses for security, message delivery monitoring and replay protection reasons.
static enum	Abi.MessageBodyType
static final record	Abi.ParamsOfAbiEncodeBoc
static final record	Abi.ParamsOfAttachSignature
static final record	Abi.ParamsOfAttachSignatureToMessageBody
static final record	Abi.ParamsOfCalcFunctionId
static final record	Abi.ParamsOfDecodeAccountData
static final record	Abi.ParamsOfDecodeBoc
static final record	Abi.ParamsOfDecodeInitialData
static final record	Abi.ParamsOfDecodeMessage
static final record	Abi.ParamsOfDecodeMessageBody
static final record	Abi.ParamsOfEncodeAccount
static final record	Abi.ParamsOfEncodeInitialData
static final record	Abi.ParamsOfEncodeInternalMessage
static final record	Abi.ParamsOfEncodeMessage
static final record	Abi.ParamsOfEncodeMessageBody
static final record	Abi.ParamsOfGetSignatureData
static final record	Abi.ParamsOfUpdateInitialData
static final record	Abi.ResultOfAbiEncodeBoc
static final record	Abi.ResultOfAttachSignature
static final record	Abi.ResultOfAttachSignatureToMessageBody
static final record	Abi.ResultOfCalcFunctionId
static final record	Abi.ResultOfDecodeAccountData
static final record	Abi.ResultOfDecodeBoc
static final record	Abi.ResultOfDecodeInitialData
static final record	Abi.ResultOfEncodeAccount
static final record	Abi.ResultOfEncodeInitialData
static final record	Abi.ResultOfEncodeInternalMessage
static final record	Abi.ResultOfEncodeMessage
static final record	Abi.ResultOfEncodeMessageBody
static final record	Abi.ResultOfGetSignatureData
static final record	Abi.ResultOfUpdateInitialData
static interface	Abi.Signer

Constructor Summary

Constructors

Constructor	Description
Abi()

Method Summary

Modifier and Type	Method	Description
static CompletableFuture<Abi.ResultOfAttachSignature>	attachSignature(int ctxId, Abi.ABI abi, String publicKey, String message, String signature)	Combines `hex`-encoded `signature` with `base64`-encoded `unsigned_message`.
static CompletableFuture<Abi.ResultOfAttachSignatureToMessageBody>	attachSignatureToMessageBody(int ctxId, Abi.ABI abi, String publicKey, String message, String signature)
static CompletableFuture<Abi.ResultOfCalcFunctionId>	calcFunctionId(int ctxId, Abi.ABI abi, String functionName, Boolean output)	Calculates contract function ID by contract ABI
static CompletableFuture<Abi.ResultOfDecodeAccountData>	decodeAccountData(int ctxId, Abi.ABI abi, String data, Boolean allowPartial)	Note: this feature requires ABI 2.1 or higher.
static CompletableFuture<Abi.ResultOfDecodeBoc>	decodeBoc(int ctxId, Abi.AbiParam[] params, String boc, Boolean allowPartial)	Solidity functions use ABI types for [builder encoding](https://github.com/tonlabs/TON-Solidity-Compiler/blob/master/API.md#tvmbuilderstore).
static CompletableFuture<Abi.ResultOfDecodeInitialData>	decodeInitialData(int ctxId, Abi.ABI abi, String data, Boolean allowPartial)	Doesn't support ABI version >= 2.4.
static CompletableFuture<Abi.DecodedMessageBody>	decodeMessage(int ctxId, Abi.ABI abi, String message, Boolean allowPartial, String functionName, Abi.DataLayout dataLayout)	Decodes message body using provided message BOC and ABI.
static CompletableFuture<Abi.DecodedMessageBody>	decodeMessageBody(int ctxId, Abi.ABI abi, String body, Boolean isInternal, Boolean allowPartial, String functionName, Abi.DataLayout dataLayout)	Decodes message body using provided body BOC and ABI.
static CompletableFuture<Abi.ResultOfEncodeAccount>	encodeAccount(int ctxId, String stateInit, BigInteger balance, BigInteger lastTransLt, Long lastPaid, Boc.BocCacheType bocCache)	Creates account state BOC
static CompletableFuture<Abi.ResultOfAbiEncodeBoc>	encodeBoc(int ctxId, Abi.AbiParam[] params, com.fasterxml.jackson.databind.JsonNode data, Boc.BocCacheType bocCache)	Encodes given parameters in JSON into a BOC using param types from ABI.
static CompletableFuture<Abi.ResultOfEncodeInitialData>	encodeInitialData(int ctxId, Abi.ABI abi, com.fasterxml.jackson.databind.JsonNode initialData, String initialPubkey, Boc.BocCacheType bocCache)	This function is analogue of `tvm.buildDataInit` function in Solidity.
static CompletableFuture<Abi.ResultOfEncodeInternalMessage>	encodeInternalMessage(int ctxId, Abi.ABI abi, String address, String srcAddress, Abi.DeploySet deploySet, Abi.CallSet callSet, String value, Boolean bounce, Boolean enableIhr)	Allows to encode deploy and function call messages.
static CompletableFuture<Abi.ResultOfEncodeMessage>	encodeMessage(int ctxId, Abi.ABI abi, String address, Abi.DeploySet deploySet, Abi.CallSet callSet, Abi.Signer signer, Integer processingTryIndex, Long signatureId)	Allows to encode deploy and function call messages, both signed and unsigned.
static CompletableFuture<Abi.ResultOfEncodeMessageBody>	encodeMessageBody(int ctxId, Abi.ABI abi, Abi.CallSet callSet, Boolean isInternal, Abi.Signer signer, Integer processingTryIndex, String address, Long signatureId)	Encodes message body according to ABI function call.
static CompletableFuture<Abi.ResultOfGetSignatureData>	getSignatureData(int ctxId, Abi.ABI abi, String message, Long signatureId)	Extracts signature from message body and calculates hash to verify the signature
static CompletableFuture<Abi.ResultOfUpdateInitialData>	updateInitialData(int ctxId, Abi.ABI abi, String data, com.fasterxml.jackson.databind.JsonNode initialData, String initialPubkey, Boc.BocCacheType bocCache)	Doesn't support ABI version >= 2.4.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Abi

public Abi()

Method Details

encodeMessageBody

public static CompletableFuture<Abi.ResultOfEncodeMessageBody> encodeMessageBody(int ctxId,
 Abi.ABI abi,
 Abi.CallSet callSet,
 Boolean isInternal,
 Abi.Signer signer,
 Integer processingTryIndex,
 String address,
 Long signatureId)
                                                                          throws EverSdkException

Encodes message body according to ABI function call.

Parameters:

abi - Contract ABI.

callSet - Must be specified in non deploy message. In case of deploy message contains parameters of constructor. Function call parameters.

isInternal - True if internal message body must be encoded.

signer - Signing parameters.

processingTryIndex - 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. Processing try index.

address - 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. Destination address of the message

signatureId - Signature ID to be used in data to sign preparing when CapSignatureWithId capability is enabled

Throws:

EverSdkException

attachSignatureToMessageBody

public static CompletableFuture<Abi.ResultOfAttachSignatureToMessageBody> attachSignatureToMessageBody(int ctxId,
 Abi.ABI abi,
 String publicKey,
 String message,
 String signature)
                                                                                                throws EverSdkException

Parameters:

abi - Contract ABI

publicKey - Must be encoded with `hex`. Public key.

message - Must be encoded with `base64`. Unsigned message body BOC.

signature - Must be encoded with `hex`. Signature.

Throws:

EverSdkException

encodeMessage

public static CompletableFuture<Abi.ResultOfEncodeMessage> encodeMessage(int ctxId,
 Abi.ABI abi,
 String address,
 Abi.DeploySet deploySet,
 Abi.CallSet callSet,
 Abi.Signer signer,
 Integer processingTryIndex,
 Long signatureId)
                                                                  throws EverSdkException

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. Public key from deploy set. 2. Public key, specified in TVM file. 3. Public key, provided by signer. Encodes an ABI-compatible message

Parameters:

abi - Contract ABI.

address - Must be specified in case of non-deploy message. Target address the message will be sent to.

deploySet - Must be specified in case of deploy message. Deploy parameters.

callSet - 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. Function call parameters.

signer - Signing parameters.

processingTryIndex - 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. Processing try index.

signatureId - Signature ID to be used in data to sign preparing when CapSignatureWithId capability is enabled

Throws:

EverSdkException

encodeInternalMessage

public static CompletableFuture<Abi.ResultOfEncodeInternalMessage> encodeInternalMessage(int ctxId,
 Abi.ABI abi,
 String address,
 String srcAddress,
 Abi.DeploySet deploySet,
 Abi.CallSet callSet,
 String value,
 Boolean bounce,
 Boolean enableIhr)
                                                                                  throws EverSdkException

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. Public key from deploy set. 2. Public key, specified in TVM file. Encodes an internal ABI-compatible message

Parameters:

abi - Can be None if both deploy_set and call_set are None. Contract ABI.

address - Must be specified in case of non-deploy message. Target address the message will be sent to.

srcAddress - Source address of the message.

deploySet - Must be specified in case of deploy message. Deploy parameters.

callSet - 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. Function call parameters.

value - Value in nanotokens to be sent with message.

bounce - Default is true. Flag of bounceable message.

enableIhr - Default is false. Enable Instant Hypercube Routing for the message.

Throws:

EverSdkException

attachSignature

public static CompletableFuture<Abi.ResultOfAttachSignature> attachSignature(int ctxId,
 Abi.ABI abi,
 String publicKey,
 String message,
 String signature)
                                                                      throws EverSdkException

Combines `hex`-encoded `signature` with `base64`-encoded `unsigned_message`. Returns signed message encoded in `base64`.

Parameters:

abi - Contract ABI

publicKey - Public key encoded in `hex`.

message - Unsigned message BOC encoded in `base64`.

signature - Signature encoded in `hex`.

Throws:

EverSdkException

decodeMessage

public static CompletableFuture<Abi.DecodedMessageBody> decodeMessage(int ctxId,
 Abi.ABI abi,
 String message,
 Boolean allowPartial,
 String functionName,
 Abi.DataLayout dataLayout)
                                                               throws EverSdkException

Decodes message body using provided message BOC and ABI.

Parameters:

abi - contract ABI

message - Message BOC

allowPartial - 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)

functionName - Function name or function id if is known in advance

Throws:

EverSdkException

decodeMessageBody

public static CompletableFuture<Abi.DecodedMessageBody> decodeMessageBody(int ctxId,
 Abi.ABI abi,
 String body,
 Boolean isInternal,
 Boolean allowPartial,
 String functionName,
 Abi.DataLayout dataLayout)
                                                                   throws EverSdkException

Decodes message body using provided body BOC and ABI.

Parameters:

abi - Contract ABI used to decode.

body - Message body BOC encoded in `base64`.

isInternal - True if the body belongs to the internal message.

allowPartial - 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)

functionName - Function name or function id if is known in advance

Throws:

EverSdkException

encodeAccount

public static CompletableFuture<Abi.ResultOfEncodeAccount> encodeAccount(int ctxId,
 String stateInit,
 BigInteger balance,
 BigInteger lastTransLt,
 Long lastPaid,
 Boc.BocCacheType bocCache)
                                                                  throws EverSdkException

Creates account state BOC

Parameters:

stateInit - Account state init.

balance - Initial balance.

lastTransLt - Initial value for the `last_trans_lt`.

lastPaid - Initial value for the `last_paid`.

bocCache - The BOC itself returned if no cache type provided Cache type to put the result.

Throws:

EverSdkException

decodeAccountData

public static CompletableFuture<Abi.ResultOfDecodeAccountData> decodeAccountData(int ctxId,
 Abi.ABI abi,
 String data,
 Boolean allowPartial)
                                                                          throws EverSdkException

Note: this feature requires ABI 2.1 or higher. Decodes account data using provided data BOC and ABI.

Parameters:

abi - Contract ABI

data - Data BOC or BOC handle

allowPartial - 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)

Throws:

EverSdkException

updateInitialData

public static CompletableFuture<Abi.ResultOfUpdateInitialData> updateInitialData(int ctxId,
 Abi.ABI abi,
 String data,
 com.fasterxml.jackson.databind.JsonNode initialData,
 String initialPubkey,
 Boc.BocCacheType bocCache)
                                                                          throws EverSdkException

Doesn't support ABI version >= 2.4. Use `encode_initial_data` instead 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.

Parameters:

abi - Contract ABI

data - Data BOC or BOC handle

initialData - `abi` parameter should be provided to set initial data List of initial values for contract's static variables.

initialPubkey - Initial account owner's public key to set into account data

bocCache - Cache type to put the result. The BOC itself returned if no cache type provided.

Throws:

EverSdkException

encodeInitialData

public static CompletableFuture<Abi.ResultOfEncodeInitialData> encodeInitialData(int ctxId,
 Abi.ABI abi,
 com.fasterxml.jackson.databind.JsonNode initialData,
 String initialPubkey,
 Boc.BocCacheType bocCache)
                                                                          throws EverSdkException

This function is analogue of `tvm.buildDataInit` function in Solidity. 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.

Parameters:

abi - Contract ABI

initialData - `abi` parameter should be provided to set initial data List of initial values for contract's static variables.

initialPubkey - Initial account owner's public key to set into account data

bocCache - Cache type to put the result. The BOC itself returned if no cache type provided.

Throws:

EverSdkException

decodeInitialData

public static CompletableFuture<Abi.ResultOfDecodeInitialData> decodeInitialData(int ctxId,
 Abi.ABI abi,
 String data,
 Boolean allowPartial)
                                                                          throws EverSdkException

Doesn't support ABI version >= 2.4. Use `decode_account_data` instead 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.

Parameters:

abi - Initial data is decoded if this parameter is provided Contract ABI.

data - Data BOC or BOC handle

allowPartial - 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)

Throws:

EverSdkException

decodeBoc

public static CompletableFuture<Abi.ResultOfDecodeBoc> decodeBoc(int ctxId,
 Abi.AbiParam[] params,
 String boc,
 Boolean allowPartial)
                                                          throws EverSdkException

Solidity functions use ABI types for [builder encoding](https://github.com/tonlabs/TON-Solidity-Compiler/blob/master/API.md#tvmbuilderstore). 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. Decodes BOC into JSON as a set of provided parameters.

Parameters:

params - Parameters to decode from BOC

boc - Data BOC or BOC handle

Throws:

EverSdkException

encodeBoc

public static CompletableFuture<Abi.ResultOfAbiEncodeBoc> encodeBoc(int ctxId,
 Abi.AbiParam[] params,
 com.fasterxml.jackson.databind.JsonNode data,
 Boc.BocCacheType bocCache)
                                                             throws EverSdkException

Encodes given parameters in JSON into a BOC using param types from ABI.

Parameters:

params - Parameters to encode into BOC

data - Parameters and values as a JSON structure

bocCache - The BOC itself returned if no cache type provided Cache type to put the result.

Throws:

EverSdkException

calcFunctionId

public static CompletableFuture<Abi.ResultOfCalcFunctionId> calcFunctionId(int ctxId,
 Abi.ABI abi,
 String functionName,
 Boolean output)
                                                                    throws EverSdkException

Calculates contract function ID by contract ABI

Parameters:

abi - Contract ABI.

functionName - Contract function name

output - If set to `true` output function ID will be returned which is used in contract response. Default is `false`

Throws:

EverSdkException

getSignatureData

public static CompletableFuture<Abi.ResultOfGetSignatureData> getSignatureData(int ctxId,
 Abi.ABI abi,
 String message,
 Long signatureId)
                                                                        throws EverSdkException

Extracts signature from message body and calculates hash to verify the signature

Parameters:

abi - Contract ABI used to decode.

message - Message BOC encoded in `base64`.

signatureId - Signature ID to be used in unsigned data preparing when CapSignatureWithId capability is enabled

Throws:

EverSdkException