Merge pull request #301 from tonlabs/1.4.0-rc

Version 1.4.0

CHANGELOG.md

@@ -1,6 +1,28 @@
 # Release Notes
 All notable changes to this project will be documented in this file.
 
+## 1.4.0 Dec 18, 2020
+
+### New
+- 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.
+
+### Fixed
+
+- **Debot Module:**
+  - Invoked debot terminated correctly after error occured 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.
+
 ## 1.3.0 Dec 8, 2020
 
 ### Featured

api/derive/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "api_derive"
-version = "1.3.0"
+version = "1.4.0"
 authors = ["Michael Vlasov <[email protected]>"]
 edition = "2018"
 

api/info/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "api_info"
-version = "1.3.0"
+version = "1.4.0"
 authors = ["Michael Vlasov <[email protected]>"]
 edition = "2018"
 

docs/mod_boc.md

@@ -16,6 +16,8 @@ null
 
 [get_boc_hash](#get_boc_hash) – Calculates BOC root hash
 
+[get_code_from_tvc](#get_code_from_tvc) – Extracts code from TVC contract image
+
 ## Types
 [ParamsOfParse](#ParamsOfParse)
 
@@ -31,6 +33,10 @@ null
 
 [ResultOfGetBocHash](#ResultOfGetBocHash)
 
+[ParamsOfGetCodeFromTvc](#ParamsOfGetCodeFromTvc)
+
+[ResultOfGetCodeFromTvc](#ResultOfGetCodeFromTvc)
+
 
 # Functions
 ## parse_message
@@ -213,6 +219,30 @@ function get_boc_hash(
 - `hash`: _string_ – BOC root hash encoded with hex
 
 
+## get_code_from_tvc
+
+Extracts code from TVC contract image
+
+```ts
+type ParamsOfGetCodeFromTvc = {
+    tvc: string
+};
+
+type ResultOfGetCodeFromTvc = {
+    code: string
+};
+
+function get_code_from_tvc(
+    params: ParamsOfGetCodeFromTvc,
+): Promise<ResultOfGetCodeFromTvc>;
+```
+### Parameters
+- `tvc`: _string_ – Contract TVC image encoded as base64
+### Result
+
+- `code`: _string_ – Contract code encoded as base64
+
+
 # Types
 ## ParamsOfParse
 ```ts
@@ -281,3 +311,21 @@ type ResultOfGetBocHash = {
 - `hash`: _string_ – BOC root hash encoded with hex
 
 
+## ParamsOfGetCodeFromTvc
+```ts
+type ParamsOfGetCodeFromTvc = {
+    tvc: string
+};
+```
+- `tvc`: _string_ – Contract TVC image encoded as base64
+
+
+## ResultOfGetCodeFromTvc
+```ts
+type ResultOfGetCodeFromTvc = {
+    code: string
+};
+```
+- `code`: _string_ – Contract code encoded as base64
+
+

docs/mod_crypto.md

@@ -28,11 +28,11 @@ null
 
 [nacl_sign](#nacl_sign) – Signs data using the signer's secret key.
 
-[nacl_sign_open](#nacl_sign_open)
+[nacl_sign_open](#nacl_sign_open) – Verifies the signature and returns the unsigned message
 
-[nacl_sign_detached](#nacl_sign_detached)
+[nacl_sign_detached](#nacl_sign_detached) – Signs the message using the secret key and returns a signature.
 
-[nacl_box_keypair](#nacl_box_keypair)
+[nacl_box_keypair](#nacl_box_keypair) – Generates a random NaCl key pair
 
 [nacl_box_keypair_from_secret_key](#nacl_box_keypair_from_secret_key) – Generates key pair from a secret key
 
@@ -550,6 +550,13 @@ function nacl_sign(
 
 ## nacl_sign_open
 
+Verifies the signature and returns the unsigned message
+
+Verifies the signature in `signed` using the signer's public key `public`
+and returns the message `unsigned`.
+
+If the signature fails verification, crypto_sign_open raises an exception.
+
 ```ts
 type ParamsOfNaclSignOpen = {
     signed: string,
@@ -575,6 +582,11 @@ function nacl_sign_open(
 
 ## nacl_sign_detached
 
+Signs the message using the secret key and returns a signature.
+
+Signs the message `unsigned` using the secret key `secret`
+and returns a signature `signature`.
+
 ```ts
 type ParamsOfNaclSign = {
     unsigned: string,
@@ -599,6 +611,8 @@ function nacl_sign_detached(
 
 ## nacl_box_keypair
 
+Generates a random NaCl key pair
+
 ```ts
 type KeyPair = {
     public: string,

docs/mod_debot.md

@@ -211,6 +211,8 @@ type ParamsOfAppDebotBrowser = {
 } | {
     type: 'Switch'
     context_id: number
+} | {
+    type: 'SwitchCompleted'
 } | {
     type: 'ShowAction'
     action: DebotAction
@@ -241,6 +243,11 @@ Switch debot to another context (menu).
 
 - `context_id`: _number_ – Debot context ID to which debot is switched.
 
+When _type_ is _'SwitchCompleted'_
+
+Notify browser that all context actions are shown.
+
+
 When _type_ is _'ShowAction'_
 
 Show action to the user. Called after `switch` for each action in context.

docs/mod_net.md

@@ -16,6 +16,8 @@ null
 
 [resume](#resume) – Resumes network module to enable network activity
 
+[find_last_shard_block](#find_last_shard_block) – Returns ID of the last block in a specified account shard
+
 ## Types
 [OrderBy](#OrderBy)
 
@@ -37,6 +39,10 @@ null
 
 [ParamsOfSubscribeCollection](#ParamsOfSubscribeCollection)
 
+[ParamsOfFindLastShardBlock](#ParamsOfFindLastShardBlock)
+
+[ResultOfFindLastShardBlock](#ResultOfFindLastShardBlock)
+
 
 # Functions
 ## query
@@ -217,6 +223,30 @@ function resume(): Promise<void>;
 
 
 
+## find_last_shard_block
+
+Returns ID of the last block in a specified account shard
+
+```ts
+type ParamsOfFindLastShardBlock = {
+    address: string
+};
+
+type ResultOfFindLastShardBlock = {
+    block_id: string
+};
+
+function find_last_shard_block(
+    params: ParamsOfFindLastShardBlock,
+): Promise<ResultOfFindLastShardBlock>;
+```
+### Parameters
+- `address`: _string_ – Account address
+### Result
+
+- `block_id`: _string_ – Account shard last block ID
+
+
 # Types
 ## OrderBy
 ```ts
@@ -333,3 +363,21 @@ type ParamsOfSubscribeCollection = {
 - `result`: _string_ – Projection (result) string
 
 
+## ParamsOfFindLastShardBlock
+```ts
+type ParamsOfFindLastShardBlock = {
+    address: string
+};
+```
+- `address`: _string_ – Account address
+
+
+## ResultOfFindLastShardBlock
+```ts
+type ResultOfFindLastShardBlock = {
+    block_id: string
+};
+```
+- `block_id`: _string_ – Account shard last block ID
+
+

docs/mod_tvm.md

@@ -2,11 +2,11 @@
 
 null
 ## Functions
-[run_executor](#run_executor)
+[run_executor](#run_executor) – Emulates all the phases of contract execution locally
 
-[run_tvm](#run_tvm)
+[run_tvm](#run_tvm) – Executes get methods of ABI-compatible contracts
 
-[run_get](#run_get) – Executes getmethod and returns data from TVM stack
+[run_get](#run_get) – Executes a getmethod of FIFT contract
 
 ## Types
 [ExecutionOptions](#ExecutionOptions)
@@ -31,6 +31,28 @@ null
 # Functions
 ## run_executor
 
+Emulates all the phases of contract execution locally
+
+Performs all the phases of contract execution on Transaction Executor -
+the same component that is used on Validator Nodes.
+
+Can be used for contract debug, to find out the reason of message unsuccessful
+delivery - as Validators just throw away failed transactions, here you can catch it.
+
+Another use case is to estimate fees for message execution. Set  `AccountForExecutor::Account.unlimited_balance`
+to `true` so that emulation will not depend on the actual balance.
+
+One more use case - you can procude the sequence of operations,
+thus emulating the multiple contract calls locally.
+And so on.
+
+To get the account boc (bag of cells) - use `net.query` method to download it from graphql api
+(field `boc` of `account`) or generate it with `abi.encode_account method`.
+To get the message boc - use `abi.encode_message` or prepare it any other way, for instance, with Fift script.
+
+If you need this emulation to be as precise as possible then specify `ParamsOfRunExecutor` parameter.
+If you need to see the aborted transaction as a result, not as an error, set `skip_transaction_check` to `true`.
+
 ```ts
 type ParamsOfRunExecutor = {
     message: string,
@@ -73,6 +95,21 @@ function run_executor(
 
 ## run_tvm
 
+Executes get methods of ABI-compatible contracts
+
+Performs only a part of compute phase of transaction execution
+that is used to run get-methods of ABI-compatible contracts.
+
+If you try to run get methods with `run_executor` you will get an error, because it checks ACCEPT and exits
+if there is none, which is actually true for get methods.
+
+ To get the account boc (bag of cells) - use `net.query` method to download it from graphql api
+(field `boc` of `account`) or generate it with `abi.encode_account method`.
+To get the message boc - use `abi.encode_message` or prepare it any other way, for instance, with Fift script.
+
+Attention! Updated account state is produces as well, but only
+`account_state.storage.state.data`  part of the boc is updated.
+
 ```ts
 type ParamsOfRunTvm = {
     message: string,
@@ -104,12 +141,15 @@ function run_tvm(
 <br>Encoded as `base64`
 - `decoded`?: _[DecodedOutput](mod_processing.md#DecodedOutput)_ – Optional decoded message bodies according to the optional `abi` parameter.
 - `account`: _string_ – Updated account state BOC.
-<br>Encoded as `base64`.Attention! Only data in account state is updated.
+<br>Encoded as `base64`.Attention! Only `account_state.storage.state.data` part of the boc is updated.
 
 
 ## run_get
 
-Executes getmethod and returns data from TVM stack
+Executes a getmethod of FIFT contract
+
+Executes a getmethod of FIFT contract that fulfills the smc-guidelines https://test.ton.org/smc-guidelines.txt
+and returns the result data from TVM's stack
 
 ```ts
 type ParamsOfRunGet = {
@@ -274,7 +314,7 @@ type ResultOfRunTvm = {
 <br>Encoded as `base64`
 - `decoded`?: _[DecodedOutput](mod_processing.md#DecodedOutput)_ – Optional decoded message bodies according to the optional `abi` parameter.
 - `account`: _string_ – Updated account state BOC.
-<br>Encoded as `base64`.Attention! Only data in account state is updated.
+<br>Encoded as `base64`.Attention! Only `account_state.storage.state.data` part of the boc is updated.
 
 
 ## ParamsOfRunGet