All notable changes to this project will be documented in this file.
- Debot module:
- Аdded
allow_no_signature
parameter todecode_and_fix_ext_msg()
andonerror_id
return value toprepare_ext_in_message()
inner functions used in TS4. - Added support for async external calls.
Query
interface extended withwaitForCollection
andquery
methods.waitForCollection
allows to wait for completion of async external calls.- Added support for DeBots with ABI 2.2.
- Аdded
- Function
proofs.proof_message_data
which proves message data, retrieved from Graphql API.
-
New module
proofs
is introduced! -
Functions
proofs.proof_block_data
andproofs.proof_transaction_data
which prove block data, retrieved from Graphql API.These are the first functions from proofs series :) Wait for others(
proof_account_data
,proof_message_data
) in the next releases.Read about them more in the documentation.
-
abi.decode_boc
function to decode custom BOC data into JSON parameters. -
Ref(<ParamType>)
type was added to ABI.
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 typeRef(<ParamType>)
which allows to storeParamType
ABI parameter in cell reference and, thus, decode manually encoded BOCs. This type is available only indecode_boc
function and will not be available in ABI messages encoding until it is included into some ABI revision.
-
boc.get_boc_depth
function to get depth of the provided boc. -
boc.decode_tvc
function returns additional fieldscode_hash
,code_depth
,data_hash
,data_depth
andcompiler_version
-
Debot module:
- added
parse
function to Json interface.
- added
boc.get_code_salt
andboc.set_code_salt
functions for contract code salt management.boc.encode_tvc
andboc.decode_tvc
functions for TVC image encoding and decodingboc.get_compiler_version
function extracting compiler version from contract codeabi.update_initial_data
andabi.decode_initial_data
function for pre-deployment contract data management
-
ABI v2.2 with fixed message body layout supported. See the specification.
Now, for contracts with ABI version < 2.2 compact layout will still be used for compatibility, for contracts with ABI version 2.2 and more - fixed layout will be used.
Please, make sure that you updated the ABI if you recompiled your contract with 2.2 ABI, or you may get an inconsistent contract behaviour. -
Debot module:
- added
getEncryptionBoxInfo
,getSigningBoxInfo
functions to Sdk interface. - implemented Query DeBot interface in DEngine.
- added
abi.encode_message
andprocessing.process_message
created invalid deploy message in case ofSigner::None
was used, and contract could not be deployed.
- Support MacOS aarch64 target
- Information about used endpoint is added to subscription errors.
- Graphql response error codes 500-599 are treated as retriable network errors
- Updated crypto libraries in order to fix building.
- http errors were not processed as network errors and didn't lead to endpoint reconnect and request retry
crypto.create_encryption_box
function for creating SDK-defined encryption boxes. First supported algorithm - AES with CBC mode.- Debot module:
- Аdded public
prepare_ext_in_message
function.
- Аdded public
tvm.run_executor
did not work when SDK is configured to use TONOS SE, because of incomplete default blockchain configuration. Now mainnet config from key block 10660619 (last key block at the moment of fix) is used as default.
- Added support of contract error messages. Error messages (for example, require(...) in Solidity) are now parsed by SDK
and returned in error message. New field
contract_error
was added to error'sdata
.
- Fixed problem with WASM binaries (everx-labs/ever-types#42)
-
ABI version
2.1
supported.
Attention! If you work with contracts, that contain String parameters, then during migration from ABI 2.0 to 2.1 you will need to remove all String type conversions to bytes and back and pass string to your contract as is. -
Now all requests to GraphQL are limited with timeout to react on unexpected server unavailability. Existing timeouts in waiting functions keep the same behaviour. All other requests timeout now can be set with
net.query_timeout
config parameter. Its default value is 60000 ms -
Debot module:
- added
encrypt
,decrypt
functions to Sdk interface which accept encryption box handles.
- added
- Deployment with empty signer in cases of public key set in TVC or deploy set.
get_address_type
function inutils
module, which validates address and returns its type. See the documentation.decode_account_data
function inabi
module that converts account data BOC into JSON representation according to ABI 2.1. See the documentation.- Diagnostic fields
filter
andtimestamp
added towait_for_collection
error main.ton.dev
andnet.ton.dev
endpoints that will be deprecated on 12.07.21 are now replaced with proper endpoints list, if they were specified in networkendpoints
config
- Search of the first master blocks during the network start period was fixed in blocks and transactions iterators
- Iterators in
net
module: robust way to iterate blockchain items (blocks, transactions) in specified range. See documentation forcreate_block_iterator
,create_transaction_iterator
,resume_block_iterator
,resume_transaction_iterator
,iterator_next
,iterator_remove
functions. - Library adds
http://
protocol to endpointslocalhost
,127.0.0.1
,0.0.0.0
if protocol isn't specified in config. - Debot module:
- added tests for Json interface.
- Added support of external encryption boxes. See the documentation
- Debot module:
- Dengine waits for completion of all transactions in a chain initiated by debot's onchain call.
timeout
option toquery_transaction_tree
– timeout used to limit waiting time for the next message and transaction in the transaction tree.
- Improved error messages regarding ABI and JSON interface. SDK now shows additional tips for the user in cases of errors.
- Warnings in Rust 1.52+. Little fixes in the documentation.
total_output
field in fees was always 0.query_transaction_tree
didn't wait for messages.
query_transaction_tree
function that returns messages and transactions tree produced by the specified message was added tonet
module. See the documentation
AbiData.key
type changed to u32.- attempt to use
orderBy
instead oforder
inquery_collection
will raise error.
-
Sync latency detection increases connection reliability. Library will change the current endpoint when it detects data sync latency on it.
-
Configuration parameters:
latency_detection_interval
,max_latency
. See client documentation for details. -
Debot module:
- signing messages with signing box handles returned from debots.
- return any sdk errors to debot in case of external calls.
- defining signing box handle used to sign message in approve callback.
- Fixed building under Rust versions older than 1.51.
- Debot module:
- implementation of Network DeBot interface in DEngine.
- implementation of
signHash
function in Sdk interface.
- Debot module:
- fixed bug in Json interface with supporting nested structures and arrays of structures.
- fixed bug in Json interface with keys containing hyphens.
-
net.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.
Subscription to counterparties collection is available vianet.subscribe_collection
function. -
Blockchain interaction reliability improvement (broadcast): library sends external inbound messages simultaneously to the N randomly chosen endpoints. If all N endpoints failed to responce then library repeats sending to another random N endpoints (except the failed one). If all the available endpoints fail to respond then library throws error. The N parameter is taken from
config.network.sending_endpoint_count
(default is 2). -
Blockchain interaction reliability improvement (bad delivery list): library tracks endpoints with bad message delivery (expired messages). These endpoints have lower priority when library chooses endpoints to send message.
-
Debot module:
- Implementation of
Json
DeBot interface in DEngine.
- Implementation of
BuilderOp::Integer.size
type has changed fromu8
tou32
.- Debot Module:
Sdk
interface functiongetAccountsDataByHash
didn't find accounts bycode_hash
with leading zero.
utils.compress_zstd
compresses data using Facebook's Zstandard algorithm.utils.decompress_zstd
decompresses data using Facebook's Zstandard algorithm.- Debot module:
init
function that creates an instance of DeBot and returns DeBot metadata.- Dengine fetches metadata form DeBot by calling 2 mandatory functions:
getRequiredInterfaces
andgetDebotInfo
. This data is returned byfetch
andinit
functions. approve
DeBot Browser callback which is called by DEngine to request permission for DeBot activities.
- Debot Module:
- [breaking]
fetch
function does't create an instance of debot. It returns DeBot metadata (DebotInfo
). - [breaking]
start
function does't create an instance of debot. It accepts DeBot handle created ininit
function.
- [breaking]
- Some internal refactor due to
ton-block
changes
- Giver address in tests is calculated from secret key. Default values are provided for TON OS SE giver
utils.calc_storage_fee
function to calculate account storage fee over a some time period.- Debot Module:
- Added unstable functions to
Sdk
interface:getAccountsDataByHash
- Added unstable functions to
- Add optional field
src_address
toParamsOfEncodeInternalMessage
. - Field
abi
inParamsOfEncodeInternalMessage
is optional and can beNone
ifcall_set
anddeploy_set
areNone
. boc.encode_boc
function provides ability to build and serialize any custom tree of cells. Application can use several base Builder serialization primitives like integers, bitstrings and nested cells.boc.get_blockchain_config
function can extract blockchain configuration from key block and also from zerostate.tvm
module functions download current blockchain configuration ifnet
is initialized with DApp Server endpoints. Otherwise default configuration is used.- Debot Module:
- Support for debot invoking in Debot Engine.
send
browser callback is used not only for interface calls but to invoke debots. start
andfetch
functions returns debot ABI.- Added new built-in interface
Hex
which implements hexadecimal encoding and decoding. - Added unstable functions to
Sdk
interface: naclBox, naclBoxOpen, naclKeypairFromSecret, getAccountCodeHash.
- Support for debot invoking in Debot Engine.
- Both
call_set
anddeploy_set
inParamsOfEncodeInternalMessage
can be omitted. In this caseencode_internal_message
generates internal message with empty body. - Debot Module:
send
function accepts one argument - serialized internal message as string encoded into base64.
- Debot browser app object and signing box app object descriptions added
- functions-helpers for enum type variable creation for Signer, Abi, ParamsOfAppDebotBrowser
- doc generator: app object interface description, constructor functions-helpers for enum type variable creation, added new line in the end if api.json
- library libsecp256k1 upgraded to fix https://rustsec.org/advisories/RUSTSEC-2019-0027
tuple_list_as_array
parameter intvm.run_get
function which controls lists representation. Default is stack-like based on nested tuples. If set totrue
then returned lists are encoded as plain arrays. Use this option if you receive this error on Web: "Runtime error. Unreachable code should not be executed..." This reduces stack size requirements for long lists.function_name
field ofCallSet
structure can be the name or id (as string in hex starting with 0x) of the called function.- Fields
config_servers
,query_url
,account_address
,gas_used
added into specific errors'ClientError.data
object.
- Binaries download links are now under https protocol
- If you receive this error on Web: "Runtime error. Unreachable code should not be executed..." in
run_get
, use the new parametertuple_list_as_array = true
. See the documentation. This may happen, for example, when elector contract contains too many participants
- Debot Module:
- Added new built-in interface
Msg
which allows to send external message to blockchain and sign it with supplied keypair.
- Added new built-in interface
crypto.hdkey_public_from_xprv
used compressed 33-byte form instead of normal 32-byte.
- BOC cache management functions were introduced:
boc.cache_set
,boc.cache_get
boc.cache_unpin
- Now functions that take boc as a parameter can also take a reference to boc cash instead so that it deсreases the number of boc serialization
and deserializations which drastically improves performance of
run_tvm
andrun_executor
expecially in case of numerous calls on the same data. boc_cache
parameter intvm.run_tvm
andtvm.run_executor
functions to save resulting messages and account BOCs into cache.return_updated_account
flag parameter introduced intvm.run_tvm
andtvm.run_executor
functions to return updated account state. Important: by default this flag isfalse
and account data is not returned.abi.encode_internal_message
function to encode an internal ABI-compatible message.- Debot Module:
- Support for get-methods and external calls in debots. Debots can send external inbound messages to destination contracts (signed - for external calls and unsigned - for get-methods) using native language syntax without actions.
- Built-in debot interfaces (interfaces implemented by DEngine). Added two built-in interfaces: base64 and Sdk.
- Added
DebotInterfaceExecutor
to automatically route messages to destination interfaces. - Debot's
fetch
function is optional now. New debots can implement onlystart
function.
- Expired message wasn't retried if local execution succeeded.
ResponseHandler
type description intomodules.md
.
net.batch_query
parameters serialization did't match to docs.- Module description in docs generator contains
null
instead of summary. - Function result section header hadn't the line separator before.
nacl_sign_detached_verify
function to verify detached signature.aggregate_collection
function as a wrapper for GraphQL aggregation queries.batch_query
function performs multiple queries per single fetch.- Active endpoint invalidation in case of network error occurring.
network.network_retries_count
config parameter is deprecated.network.max_reconnect_timeout
is introduced that allows to specify maximum network resolving timeout. Default value is 2 min.initial_pubkey
field inDeploySet
to specify public key instead of one from TVC file or provided by signer.- Support for debot interfaces:
send
Browser Callback to send messages with interface calls to Browser.- new variant
ParamsOfAppDebotBrowser::Send
. send
API function to send messages from Browser to Debot.run_output.rs
- internal structure RunOutput to filter messages generated by debot to 4 categories: interface calls, external calls, get-method calls and invoke calls.
- Device time synchronization is checked only in
send_message
. Data querying does not require proper time now
net
module functions waits fornet.resume
call instead of returning error if called while the module is suspended
- How to work with
Application Objects
specification added
- Updated the dependence on
ton-labs-abi
reconnect_timeout
parameter inNetworkConfig
.endpoints
parameter inNetworkConfig
. It contains the list of available server addresses to connect. SDK will use one them with the least connect time.server_address
parameter is still supported butendpoints
is prevailing.net.fetch_endpoints
function to receive available endpoints from server.net.set_endpoints
function to set endpoints list for using on next reconnect.ErrorCode
type in each module spec inapi.json
.
- send
GQL_TERMINATE_CONNECTION
and close websocket on leaving ws loop.
- GraphQL optimization: use single web socket to serve all subscriptions.
- Support for the
keep-alive
messages from the GraphQL server. tonclient-core-version
http header.net.find_last_shard_block
function returning account shard last block ID.boc.get_code_from_tvc
function extracting contract code from TVC image.- Debot Module:
- Add new variant
ParamsOfAppDebotBrowser::SwitchCompleted
to notify browser when all context actions are shown. - Added new 3 engine routines for crypto operations and 1 routine for querying account state (balance, state type, code, data) that can be used in debots.
- Add new variant
- Debot Module:
- Invoked debot terminated correctly after error occurred during execution of one of its actions. Initial prev_state of invoked debot changed to STATE_EXIT.
- Fixed double jumping to current context in invoker debot after returning control to it from invoked debot.
- Fixed conversation of exception codes thrown by debots to their user-friendly description.
net.query
method . Performs custom graphql query that can be copied directly from the playground.net.suspend
andnet.resume
methods for disabling and enabling network activity. One of the possible use-cases is to manage subscriptions when a mobile application is brought to the background and into the foreground again.- Smart summary and description doc separation.
- ts-generator includes doc comments in JSDoc format.
-
UNSTABLE API. This API is experimental. It can be changed in the next releases.
debot
module was added with debot engine functions, such as :start
,fetch
,execute
,remove
. See thedebot
module documentation for more info. Check our tests for code examples. -
External signing was supported for message encoding:
SigningBox
type forSigner
enum was supported. Now it is possible to sign messages with externally implemented signing box interface without private key disclosure to the library. Can be used in case of signing via HSM API or via cold wallet - when there is no access to the private key.It is also possible to create a Signing Box instance inside SDK - from a key pair passed into the library with
get_signing_box
method. It can be used for some test cases. Also it increases security - you need to pass your keys one time only.Check the
crypto
module documentation forSigningBoxHandle
type andregister_signing_box
,get_signing_box
,signing_box_get_public_key
,signing_box_sign
. Check our tests for code examples.
- panic after
tc_destroy_context
call. Now all contexts use global async runtime - field
mnemonic_hdkey_compliant
was removed fromCryptoConfig
(unused by the library) - original and resolved errors are swapped in result. Now
error.code
contains original error code
wasm
feature has been fixedcrypto.factorize
doesn't panic on invalid challengeclient.get_api_reference
returns proper version- ABI JSON with explicit function ID is parsed properly
- Compatible with older rust version change api type derivation with
vec![]
instead of prev[].into()
- ChaCha20 encryption support
crypto.chacha20
. boc.parse_shardstate
function for shardstates parsing.boc.get_boc_hash
function for calculating BOC root hashclient.build_info
fully defined and documented.processing.wait_for_transaction
andprocessing.process_message
functions execute contract locally in case if transaction waiting fails in order to resolve the contract execution errorrun_executor
,run_tvm
now returnexit_arg
in case of TVM errors.- Create the
build_info.json
on the build stage. Abi::Contract
variant as an alias to deprecatedAbi::Serialized
Abi::Json
variant to specify an ABI as a raw JSON string.api.json
now contains details about numeric types: Number and BigInt are now have new fieldsnumber_type
andnumber_size
.api.json
ref type names are fully qualified now in form ofmodule.type
, for exampleabi.Signer
.
- TS generator fix some field names that is an invalid JS identifiers.
- Use
install_name_tool
to fix loading library paths atlibton_client.dylib
. api.json
is reduced, so it can't contains tuple types, only structs. All types are exactly match to JSON.out_of_sync_threshold
config parameter isu32
tc_request_ptr
function to use pointersvoid*
instead of request_idu32
. This feature is UNSTABLE yet.
- All api functions are defined in mod.rs of appropriate modules
- Function names are the same as API function names:
module.function_name
- Parameters naming:
- In snake case
- Base64 suffix is removed from parameter names. For example,
bocBase64
is changed toboc
- Parsed boc replaced with unparsed boc in all function input parameters
- All functions take byte arrays in a defined encoding:
base64
- encoding used for byte arrays of variable length: text, images, etc.hex-lower-case
- encoding used to encode fixed length bit sequences: hashes, keys, salt, etc.
contracts
module is splitted into 5 modules:tvm
- embedded TVM execution functionsboc
- raw cell and BOC manipulation functionsabi
- abi-compatible messages creation and parsing functionsprocessing
- blockchain interaction functionsutils
- has onlyconvert_address
ATM, later will be used for some useful stuff
query
module is renamed tonet
- new
client
module with functionsversion
,api_reference
- All the environment functions (fetch, websocket, spawn, now, etc.) were abstracted behind a separate environment layer crate
ClientEnv
. The standard core env layer implementation is instd_client_env
. Later (in 1.1 release)web_client_env
implementation for Web will be added. - Error codes are distributed across the modules the following way:
client
- 0..99,crypto
- 100..199,boc
- 200..299,abi
- 300..399,tvm
- 400..499,processing
- 500..599,net
- 600..699 - Error descriptions related to a module are described in error.rs file in the module's folder
decode_message
,process_message
,wait_for_transaction
,run_tvm
,run_executor
, etc. (all the functions that return decoded messages) now returns int*/uint* data as a string which can be either decimal or 0x-prefixed hex string. Hex representation can be in any register and have any number of leading zeroes.
-
All the functions are asynchronous
-
All the functions that can be called via JSON-api are public, so that they can be used directly without JSON-api.
-
Inline documentation and api reference added.
-
[breaking]
interops.rs
,tonclient.h
.create_context
now takesconfig
parameter - context creation and setup happen at the same time. Config structure has been changed. -
[breaking]
crypto module.
default values for mnemonic-related functions have been changed:dictionary is 1, for word count is 12, derivation path is 'm/44'/396'/0'/0/0
-
[breaking] crypto module. removed
word_count
parameter fromwords
function -
[breaking] crypto module.
compliant
parameter is removed from functionsmnemonic_derive_sign_keys
,hdkey_xprv_derive_path
,hdkey_xprv_derive
, -
[new] boc module. Functions
parse_block
,parse_account
,parse_message
,parse_transaction
that parse bocs to JSONs are introduced. -
[breaking] net module. Functions
query
,wait.for
,subscribe
are renamed toquery_collection
,wait_for_collection
,subscribe_collection
table
parameter is renamed tocollection
.filter
parameter is now optional and ofjson
type (passed as json object instead ofstring
) -
[breaking] net module. Function
get.next
is removed. -
[breaking] net module.
subscribe_collection
now uses callback to return data. -
[breaking] abi module.
decode_message
introduced instead ofdecode_unknown_run
,decode_run_output
-
[breaking] abi module.
encode_message
introduced instead ofencode_unsigned_deploy_message
,encode_unsigned_run_message
,run.encode_message
,deploy.encode_message
-
[breaking] abi module.
signer: Signer
parameter used instead ofkey_pair: KeyPair
, which can be ofNone
(unsigned message will be produced),External
(data to be signed +unsigned message),Keys
(signed message will be produced),SigningBox
(message will be signed using a provided interface - will be supported in coming releases) -
[breaking] processing module.
process_message
introduced instead ofdeploy
andrun
. Parameter set was drastically changed. -
[breaking] processing module.
process_message
- now, if the contract was already deployed, deploy fails with an exception of double constructor call. -
[new] processing module.
process_message
- any function can be called at deploy, not only constructor, also there can be no function call. -
[new] processing module.
process_message
now can optionally use callback to monitor message processing (creation, sending, shard block fetching, transaction receiving). -
[fixed] processing module.
process_message
- deploy can be performed without a key pair -
[breaking] tvm module.
run_local
is divided into 2 functionsrun_tvm
andrun_executor
. -
[new] tvm module.
run_tvm
function - performs contract code execution on tvm (part of compute phase). Helps to run contract methods without ACCEPT. Returns account state with updated data, list of external messages and (optional, for ABI contracts only) list of messages decoded data. -
[new] tvm module.
run_executor
function - performs full contract code execution on Transaction Executor (part of collator protocol that performs all phases and checks and - as a successful result - forms a transaction) Returns updated account state, parsed transaction, list of parsed messages with optional decoded message bodies. -
[breaking] tvm module.
run_get
does not download account boc from the network anymore, but takes account boc as a parameter.
config.get_api_reference
api function (pre release).ton_sdk_cli
cli tool (pre release).- full local run functions use
LocalRunContext
to exactly reproduce all transaction parameters and produce the same result as node
waitForTransaction
didn't use prev_alt_ref for block walking
- All methods that require contract's code/data can use field
boc
in account document to extract code and data (instead ofcode
anddata
fields). - Optional
bocBase64
parameter of methodtvm.get
that can be used instead ofcodeBase64
anddataBase64
.
error.data
object extended with fieldsaddress
,function_name
,account_balance
,account_address
,query_url
,config_server
for appropriate errors
- supports for core context in all platforms
- local run functions return updated contract state when running with
full_run = true
- time sync check while initializing
- parallel requests on different contexts don't block each other. Requests on the same context remain sequential
- new transaction wait mechanism. All account's shard blocks are checked for transaction to guarantee message expiration
contracts.wait.transaction
function for awaiting previously sent message processingcontracts.send.message
returns message processing state forcontracts.wait.transaction
functioncontracts.find.shard
function for account shard matching- added logging on warning messages
- error resolving by local message processing
contracts.resolve.error
function for manual error resolving callcontracts.process.transaction
function processing transaction to check errors and get outputcontracts.run.local
andcontracts.run.local
functions now havefullRun
flag to emulate node transaction processing and calculate feestonsdk
command line tool.ton_client
functionget_method_names
.
- TON mnemonic functions didn't check validity of the seed phrase.
- Platform builder generates ready to use
index.js
for web clients (instead of install script ofton-client-web-js
binding)
tvm.get
now can fetch account data if it is not provided
- Message processing functions added
- Run get methods function added
ed25519-dalek
version updated to1.0.0-pre.3
- SDK is fully open sourced since open repo
ton-labs-executor
used
- Panic in fee calculation under WASM
reqwest
crate version synced in all projects- Memory leaking in Node JS