From 09c04b494b301653dd0d68590ac858f346f0f5c2 Mon Sep 17 00:00:00 2001 From: IgorKoval Date: Tue, 23 Apr 2024 00:27:33 +0300 Subject: [PATCH 1/2] Fix docs --- Cargo.lock | 8 +-- Cargo.toml | 2 +- README.md | 152 ++++-------------------------------------------- build.rs | 2 +- src/abi.rs | 2 +- src/keyman.rs | 2 +- src/lib.rs | 2 +- src/main.rs | 12 ++-- src/printer.rs | 2 +- src/program.rs | 2 +- src/testcall.rs | 2 +- 11 files changed, 26 insertions(+), 162 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 173f28f0..177c6fac 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -740,9 +740,9 @@ dependencies = [ [[package]] name = "fiat-crypto" -version = "0.2.7" +version = "0.2.8" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c007b1ae3abe1cb6f85a16305acd418b7ca6343b953633fee2b76d8f108b830f" +checksum = "38793c55593b33412e3ae40c2c9781ffaa6f438f6f8c10f24e71846fbd7ae01e" [[package]] name = "float-cmp" @@ -861,9 +861,9 @@ checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b" [[package]] name = "jobserver" -version = "0.1.30" +version = "0.1.31" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "685a7d121ee3f65ae4fddd72b25a04bb36b6af81bc0828f7d5434c0fe60fa3a2" +checksum = "d2b099aaa34a9751c5bf0878add70444e1ed2dd73f347be99003d4577277de6e" dependencies = [ "libc", ] diff --git a/Cargo.toml b/Cargo.toml index a329d2e5..58faa189 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -9,7 +9,7 @@ license-file = 'LICENSE.md' name = 'tvm_linker' readme = 'README.md' repository = 'https://github.com/everx-labs/TVM-linker' -version = '0.21.2' +version = '0.21.3' [[bin]] name = 'tvm_linker' diff --git a/README.md b/README.md index f294e4a0..7987973e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,7 @@ # TVM linker -This repository stores the source code for tvm_linker utility. It takes TVM (https://test.ton.org/tvm.pdf) -assembly source code of TON smart contract, compiles it and links its parts, adds standard selector -and runtime and stores it into binary TVC file. Also, it can immediately execute a smart -contract by emulating the computing phase of TON transaction. - -TVM assembly can be generated by one of TVM compilers: -- TVM solidity compiler (https://github.com/everx-labs/TVM-Solidity-Compiler) -- C and C++ compiler for TVM (https://github.com/everx-labs/TON-Compiler) +This repository stores the source code for `tvm_linker` utility. It can immediately execute a smart +contract by emulating the computing phase of transaction. ## Prerequisites @@ -18,154 +12,28 @@ TVM assembly can be generated by one of TVM compilers: ## How to build ```bash -$ cargo update && cargo build --release -j8 +$ cargo update && cargo build --release ``` ## How to use -tvm_linker has several modes of work: - -### 1) Generating a ready-to-deploy contract. - -```bash -$ tvm_linker compile [--lib ] [--abi-json ] [-w ] [--debug] [--print_code] [--silent] [--debug-map ] -``` - -Here `source` is a name of tvm assembly source file, `library` is a runtime library file (can be more than one: `--lib` -should be supplied for every file). If `--lib` option is not specified linker looks for environment variable -`TVM_LINKER_LIB_PATH`, if it is set that path is used to load a library. - -If there is an ABI file, it is better to use `--abi-json` option to supply a contract ABI file. Function IDs are -generated according to function signatures in the ABI. If neither `-a` nor `--abi-json` option is specified, linker -checks whether file `source`(without extension) + `.abi.json` exists. If file exists, linker loads ABI from it. - -Linker generates the `
.tvc` file, where `
` is a hash from initial data and code of the contract. - -Linker prints initial contract address in different formats: raw and user-friendly (testnet and mainnet). Define the workchain -ID option `-w` to generate proper user-friendly address. -1 is used by default. - -To add a key to the contract data and obtain real contract address user should use [`ever-cli genaddr` command](https://github.com/everx-labs/ever-cli/blob/master/README.md#41-generate-contract-address). - -While execution if option `--debug-map ` is specified, this command can generate a debug info file, -which contains mapping that can bind contract code with source files. This file can be used while debugging the -contract. - -`--print_code` option allows user only generate code and print it without creating the TVC file. -`--silent` option mutes all extra notifications. - -### 2) Decoding of .boc messages prepared externally. -To use this method, call - -```bash -$ tvm_linker decode [--tvc] boc-file -``` - -If `--tvc` is omitted, `boc-file` is a file with a serialized message, otherwise it is a contract `tvc` file. - -### 3) Preparing an external inbound messages in .boc format. - -First, generate a contract as described in 1). Then use `message` subcommand to create external inbound message in boc -format: +`tvm_linker` has several modes of work: + * Decoding of `.boc` messages prepared externally. ```bash -$ tvm_linker message [--init] [--data] [-w] -$ tvm_linker message [--init] --abi-json --abi-method --abi-params {json_with_params} [-w] +tvm_linker decode ... ``` - -`contract-address` - the name of the compiled contract file without extension. The contract .tvc file should be placed in the current directory. - -To create a `constructor message` with contract's code and data, use `--init` option. - -Additionally, you can add a raw body to the message. Use the `--data` option: - + * Preparing an external inbound messages in `.boc` format. ```bash -$ tvm_linker message --data +tvm_linker message ... ``` - -Instead of ``, specify the necessary message body in hex format. - -Or make a message with ABI call using combination of options: -- `--abi-json ` - path to a .json with contract interface described according to ABI specification; -- `--abi-method ` - name of the contract method to call; -- `--abi-params {}` - arguments of the method declared in json like this: `{"arg_a": "0x1234", "arg_b": "x12345678"}`. - -By default, -1 is used as a workchain id in contract address. To use another one, use `-w` option: - -```bash -$ tvm_linker message -w 0 -``` - -### 4) Emulating contract execution: + * Emulating contract execution: Linker can emulate compute phase of blockchain transaction. It is useful for contract debugging. ```bash -$ tvm_linker test --body XXXX... [--sign key-file] [--trace] [--decode-c6] [--internal ] [--src address] [--now unixtime] [-s source-file] [--balance ] +tvm_linker test ... ``` -Loads contract from file by contract address `address` and emulates contract call sending external inbound message (by default) with body defined after `--body` parameter to the contract. `XXXX...` is a hex string. - -If `--sign` specified, the body will be signed with the private key from `key-file` file. - -Use `--trace` flag to trace VM execution: stack, registers and gas will be printed after each executed VM command. - -Use `--decode-c6` to see output actions in user-friendly format. - -Use `--balance ` to define account balance in nanograms. It will be available at the bottom of initial stake and in SmartContractInfo tuple from c7 register . - -Use `--config ` to define the config parameters to run VM with. The TVC file is a state of the config smart-contract. -The capabilities field of the config defines the VM mode of operation. If the config parameter is omitted, the capabilities default value of 0x880116ae is used. -For the available capability codes consult [here](https://github.com/everx-labs/ever-block/blob/master/src/config_params.rs#L336) - -Note: configuration smart-contract resides at the address: -1:5555555555555555555555555555555555555555555555555555555555555555 - - -Use `--internal` to send internal message to the contract with defined nanograms in `value`. By default, source address in internal message in zero address (`0000...0000`), to define another address use option `--src
`, where address should be in the format : (i.e. "0:1122...AABB"). - -Account and message balance can have extended format with extra currencies: `{ "main": int, "extra": {"i": int, ...} }`. - -Example: `--internal 100000 --src "0:6011b66a47238cf992f1033fe6aff00ce0f850df387ee92468d9c26b5564ba53"` - -Use `--now ` option to define transaction creation time. By default, current time is used. - -Use `--bounced` flag to emulate bounced internal message, use this flag only with `--internal` option. - -An ABI body can be generated if `abi-params`, `abi-json` and `abi-method` will be used instead of `--body XXXX...`. - -If `--body` is used, contract's public function ids can be encoded by their names using `$...$` syntax:`$name:[0len][type]$`, -where `name` is a name of public function, `len` - length in chars of the id (if `len` is bigger than `name`'s length in chars than -zeros will be added on the left side to fit required length), `type` can be `x` or `X` - hexadecimal integer in lowercase or uppercase. You have to set `-s source` option when you use $...$ syntax. - -Example: - -```bash -$ tvm_linker address test --body 00$main$ -s source //main id will be inserted as decimal string. Dont use this case, just as example -$ tvm_linker address test --body 00$main:08X$ -s source -$ tvm_linker address test --body 00$main:X$ -s source -$ tvm_linker address test --body 00$main:x$ -s source -``` - -The `--body-from-boc` option is analogous to `--body` but extracts the message body from the specified message boc file. - -### 5) Disassembler - -There are a number of tools under the `disasm` umbrella: - -`dump` outputs a pseudo-graphical representation of a tree of cells. -`text` disassembles a tvc produced by Solidity and FunC compilers. -`graphviz` produces an output in dot format for generation of graphical DAG representation of a tvc. - ### More Help Use `tvm_linker --help` for detailed description about all options, flags and subcommands. - -## Input format - -As a temporary measure, some LLVM-assembler like input is used. The source code should contain several function types: - -- `.internal` - special functions, which are used only by contract's runtime. There are some wellknown internal functions: - - `main_external`, `main_internal`, `onTickTock`, `onBounce`. - -## Support - -Get more documents at docs.ton.dev and check our [YouTube Channel](https://www.youtube.com/channel/UC9kJ6DKaxSxk6T3lEGdq-Gg) for tutorials. Stay tuned. diff --git a/build.rs b/build.rs index 7462c484..14a70663 100644 --- a/build.rs +++ b/build.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ use std::process::Command; diff --git a/src/abi.rs b/src/abi.rs index a3d7e452..45fabef7 100644 --- a/src/abi.rs +++ b/src/abi.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ use ever_abi::{Contract, json_abi::{encode_function_call, decode_function_response}}; diff --git a/src/keyman.rs b/src/keyman.rs index c5d59a3b..2ac4e0d7 100644 --- a/src/keyman.rs +++ b/src/keyman.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ use failure::format_err; diff --git a/src/lib.rs b/src/lib.rs index 956b748c..0d283eec 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ diff --git a/src/main.rs b/src/main.rs index f21df871..d233eff1 100644 --- a/src/main.rs +++ b/src/main.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ @@ -51,20 +51,17 @@ fn linker_main() -> Status { ); let matches = clap_app!(tvm_linker => (version: build_info.as_str()) - (author: "TON Labs") (about: "Tool for executing TVM code") (@subcommand decode => - (about: "take apart a message boc or a tvc file") + (about: "Take apart a message boc or a tvc file") (version: build_info.as_str()) - (author: "TON Labs") (@arg INPUT: +required +takes_value "BOC file") (@arg TVC: --tvc "BOC file is tvc file") ) (@subcommand test => (@setting AllowLeadingHyphen) - (about: "execute contract in test environment") + (about: "Execute contract in test environment") (version: build_info.as_str()) - (author: "TON Labs") (@arg SOURCE: -s --source +takes_value "Contract source file") (@arg BODY: --body +takes_value "Body for external inbound message (a bitstring like x09c_ or a hex string)") (@arg BODY_FROM_BOC: --("body-from-boc") +takes_value "Body from message boc file") @@ -90,9 +87,8 @@ fn linker_main() -> Status { ) (@subcommand message => (@setting AllowNegativeNumbers) - (about: "generate inbound message for the blockchain") + (about: "Generate inbound message for the blockchain") (version: build_info.as_str()) - (author: "TON Labs") (@arg INIT: -i --init "Generates constructor message with code and data of the contract") (@arg DATA: -d --data +takes_value "Supplies body for the message in hex format (empty data by default)") (@arg INTERNAL: --internal +takes_value "Generates inbound internal message with provided value (instead of external message by default)") diff --git a/src/printer.rs b/src/printer.rs index 0061532a..0619a438 100644 --- a/src/printer.rs +++ b/src/printer.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ use failure::format_err; diff --git a/src/program.rs b/src/program.rs index 82cfcf84..f4017e01 100644 --- a/src/program.rs +++ b/src/program.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ use base64::encode; diff --git a/src/testcall.rs b/src/testcall.rs index 1bedaec5..b5d019e3 100644 --- a/src/testcall.rs +++ b/src/testcall.rs @@ -7,7 +7,7 @@ * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific TON DEV software governing permissions and + * See the License for the specific EVERX DEV software governing permissions and * limitations under the License. */ From c173638c06a3fba8096962e671d45562f1019d27 Mon Sep 17 00:00:00 2001 From: tonjen Date: Mon, 22 Apr 2024 21:48:13 +0000 Subject: [PATCH 2/2] Preparing to merge with the master #nolog --- Cargo.lock | 18 +++++++++--------- Cargo.toml | 8 ++++---- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index 177c6fac..80ec7f9a 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -634,8 +634,8 @@ checksum = "a47c1c47d2f5964e29c61246e81db715514cd532db6b5116a25ea3c03d6780a2" [[package]] name = "ever_abi" -version = "2.5.1" -source = "git+https://github.com/everx-labs/ever-abi.git?tag=2.5.1#e80c51cd9b890e036c31a1dab7e798cc9f8e9ba5" +version = "2.5.2" +source = "git+https://github.com/everx-labs/ever-abi.git?tag=2.5.2#99397220767349e4d065dcb303b87c1f102948ad" dependencies = [ "base64 0.10.1", "byteorder", @@ -653,8 +653,8 @@ dependencies = [ [[package]] name = "ever_assembler" -version = "1.5.3" -source = "git+https://github.com/everx-labs/ever-assembler.git?tag=1.5.3#3e991c1fbbf410268e114f80709d403d327cf1be" +version = "1.5.4" +source = "git+https://github.com/everx-labs/ever-assembler.git?tag=1.5.4#4a1c5d85cf031bca45b762936847be3a30ef2835" dependencies = [ "clap 4.5.4", "ever_block", @@ -670,8 +670,8 @@ dependencies = [ [[package]] name = "ever_block" -version = "1.10.0" -source = "git+https://github.com/everx-labs/ever-block.git?tag=1.10.0#f7c5194d082e0d2412571e981aa0b1b500c559da" +version = "1.10.1" +source = "git+https://github.com/everx-labs/ever-block.git?tag=1.10.1#5585871d1022770ea6a60e824dd2767cb5bfde1c" dependencies = [ "aes-ctr", "base64 0.13.1", @@ -698,8 +698,8 @@ dependencies = [ [[package]] name = "ever_vm" -version = "2.1.2" -source = "git+https://github.com/everx-labs/ever-vm.git?tag=2.1.2#75c73db756157305788e7323ce5f7f8ad8eb4da8" +version = "2.1.3" +source = "git+https://github.com/everx-labs/ever-vm.git?tag=2.1.3#ff63e661e98b39c963caf4029df40f522a51918f" dependencies = [ "diffy", "ed25519 1.5.3", @@ -1494,7 +1494,7 @@ dependencies = [ [[package]] name = "tvm_linker" -version = "0.21.2" +version = "0.21.3" dependencies = [ "assert_cmd", "base64 0.13.1", diff --git a/Cargo.toml b/Cargo.toml index 58faa189..59c0dd15 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -31,10 +31,10 @@ serde = { features = [ 'derive' ], version = '1.0' } serde_json = '1.0' sha2 = '0.10' simplelog = '0.6' -ever_abi = { git = 'https://github.com/everx-labs/ever-abi.git', tag = '2.5.1' } -ever_assembler = { features = [ 'gosh' ], git = 'https://github.com/everx-labs/ever-assembler.git', tag = '1.5.3' } -ever_block = { features = [ 'gosh' ], git = 'https://github.com/everx-labs/ever-block.git', tag = '1.10.0' } -ever_vm = { features = [ 'gosh' ], git = 'https://github.com/everx-labs/ever-vm.git', tag = '2.1.2' } +ever_abi = { git = 'https://github.com/everx-labs/ever-abi.git', tag = '2.5.2' } +ever_assembler = { features = [ 'gosh' ], git = 'https://github.com/everx-labs/ever-assembler.git', tag = '1.5.4' } +ever_block = { features = [ 'gosh' ], git = 'https://github.com/everx-labs/ever-block.git', tag = '1.10.1' } +ever_vm = { features = [ 'gosh' ], git = 'https://github.com/everx-labs/ever-vm.git', tag = '2.1.3' } [dev-dependencies] assert_cmd = '2.0.5'