diff --git a/README.md b/README.md index e79e0cb..1b0f1bf 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ We provide tow branches now: We may keep it in this way until `pallet-contracts` release v3.0.0 * `master` branch is our default branch, which provides our forked `pallet-contracts` crate that tracks the newest substrate `pallet-contracts` module. - + In `master` branch, Europa use `vender/substrate`'s `pallet-contracts` as dependency. This forked `pallet-contracts` is from the branch `europa-contracts` in our `vendor/substrate` repo. In this forked `pallet-contracts` Europa provides many self test features. @@ -70,7 +70,7 @@ Europa **current** "extending types" is (This may be changed for different Europ "Address": "MultiAddress" } ``` - + ## Features In details, current Europa sandbox framework provides: 1. This framework is another implementation for [substrate client](https://github.com/paritytech/substrate/tree/master/client). @@ -100,7 +100,8 @@ Europa self modifications: - [ ] Using `wasmtime` as WASM JIT-executor and support gdb/lldb debug. (developing) - [ ] Using `wasm3` as a more faster WASM interpreter. (not in plan) - [x] Supporting `NestedRuntime` event track feature to record all useful thing in `pallet-contracts`. - When instantiate or call a contract (This contract needs to be compiled by [PatractLabs's `cargo-contract`](https://github.com/patractlabs/cargo-contract/tree/cmd/debug) now), Europa would print: + When instantiate or call a contract (This contract needs to be compiled by [PatractLabs's `cargo-contract`](https://github.com/patractlabs/cargo-contract/) now), Europa would print: + ```bash 1: NestedRuntime { ext_result: [success] ExecReturnValue { flags: 0, data: 01 }, @@ -130,7 +131,7 @@ ChainExtensions features: *Currently we use a simple static way to charge weight for ZKP, we would change this part with benchmarks result in future.* More information about Europa `pallet-contracts` sandbox detailed features refers to the doc: [europa.md](./doc/europa.md) - + ## Build and run ### Build #### clone this repo diff --git a/doc/europa.md b/doc/europa.md index 400941c..a6b0f7a 100644 --- a/doc/europa.md +++ b/doc/europa.md @@ -30,18 +30,18 @@ We do following things to support those features: * ChainExtension: * Contract logger - We integrate the lib which is provided by PatractLabs: [ink-log](https://github.com/patractlabs/ink-log). This + We integrate the lib which is provided by Patract: [ink-log](https://github.com/patractlabs/ink-log). This lib pass log data from contract to Europa through ChainExtensions. * ZKP feature - We integrate the lib which is provided by PatractLabs: [megaclite](https://github.com/patractlabs/megaclite). + We integrate the lib which is provided by Patract: [megaclite](https://github.com/patractlabs/megaclite). This lib providers different curves to support basic function to run Groth16 algorithm in contracts. ### Prepare -For using all features when running contracts in Europa, we advice developers use [Patract Labs's `cargo-contract`](https://github.com/paritytech/cargo-contract) +For using all features when running contracts in Europa, we advice developers use [Patract's `cargo-contract`](https://github.com/paritytech/cargo-contract) to compile ink! contract, until [this pr#131 Enable debug info to the source warehouse with flag in command build](https://github.com/paritytech/cargo-contract/pull/131) could be merged by paritytech. -In Patract Labs's `cargo-contract`, we will contain the "name section" while compile contracts. Before this PR is merged, -currently, only the `cargo-contract` version provided by us (Patract Labs) can be used: +In Patract's `cargo-contract`, we will contain the "name section" while compile contracts. Before this PR is merged, +currently, only the `cargo-contract` version provided by us (Patract) can be used: ```bash cargo install --git https://github.com/patractlabs/cargo-contract --branch v0.10.0 --force @@ -77,25 +77,25 @@ FLAGS: Emits debug info into wasm file ``` -It means that you are using the `cargo-contract` provided by Patract Labs. If you want to see the backtrace of the WASM +It means that you are using the `cargo-contract` provided by Patract. If you want to see the backtrace of the WASM contract execution crash while using Europa, you need to add the `--debug` command when compiling the contract. Using the `--debug` command will generate file in the `target/ink` directory of the originally compiled contract, -ending with `*.wasm`. This `*.wasm` file is the WASM contract file containing the "name section" part. +replacing original `*.wasm/*.contract` file. **Notice that the file generated by this method is usually much larger than the original file**, for the `*.wasm/*.contract` file is the WASM contract file containing the "name section" part. -**If you need to use Europa for testing, the contract deployed to Europa needs to use this `*.wasm` file instead of the originally generated `*opt.wasm` file.** +**If you need to use Europa for testing, the contract deployed to Europa needs to use the file `*.wasm/*.contract` compiled by adding `-d/--debug` instead of the originally generated file.** -> In following doc, about the log part, if the contract do not have "name section" (contracts are not compiled by `--debug` -> or not submit `*.wasm` file), the output may contain a batch of ``. If you meet this, please use the contract +> In following doc, about the log part, if the contract do not have "name section" (contracts are not compiled by `--debug`), the output may contain a batch of ``. If you meet this, please use the contract > which has "name section". +> > ```bash > wasm_error: Error::WasmiExecution(Trap(Trap { kind: Unreachable })) -> wasm backtrace: -> | [...] -> | [...] -> ╰─>[...] +> wasm backtrace: +> | [...] +> | [...] +> ╰─>[...] > ``` - + ### Design and examples #### 1. Contract execution event tracker In our forked `pallet-contracts`, we define the struct `NestedRuntime` to track the event when developers execute contracts: @@ -222,7 +222,7 @@ Let's explain the information printed above: 1. After A calls B, it returns to A to continue execution, and then calls contract C - ![call_other_1](/Users/jenner/codes/substrate-contracts-book/src/zh_CN/europa/img/call_other_1.png) + ![call_other_1](imgs/call_other_1.png) Then it will produce a log print similar to the following: @@ -244,7 +244,7 @@ Let's explain the information printed above: 2. After A calls B, B calls contract C again, and finally returns to A - ![call_other_2](/Users/jenner/codes/substrate-contracts-book/src/zh_CN/europa/img/call_other_2.png) + ![call_other_2](imgs/call_other_2.png) Then it will produce a log print similar to the following: @@ -462,12 +462,10 @@ More information refers to [ink-log](https://github.com/patractlabs/ink-log). ##### 3.2 ZKP feature More information refers to [megaclite](https://github.com/patractlabs/megaclite), and the example contracts in [metis/groth16](https://github.com/patractlabs/metis/tree/master/groth16). - - #### Other examples: ##### Example 1：`ContractTrap` caused by locating duplicate topics -Some time ago, we (Patract Labs) reported a bug to `ink!`, see issue:["When set '0' value in contracts event, may cause `Error::ContractTrapped` and panic in contract #589" ](https://github.com/paritytech/ink/issues/589). It is very difficult to locate this error before Europa has developed the relevant function. Thank you @athei [located the error](https://github.com/paritytech/ink/issues/589#issuecomment-731571918). Here we reproduce this error and use Europa's log to quickly analyze and locate the place where the bug appears: +Some time ago, we (Patract) reported a bug to `ink!`, see issue:["When set '0' value in contracts event, may cause `Error::ContractTrapped` and panic in contract #589" ](https://github.com/paritytech/ink/issues/589). It is very difficult to locate this error before Europa has developed the relevant function. Thank you @athei [located the error](https://github.com/paritytech/ink/issues/589#issuecomment-731571918). Here we reproduce this error and use Europa's log to quickly analyze and locate the place where the bug appears: 1. checkout `ink!` to commit `8e8fe09565ca6d2fad7701d68ff13f12deda7eed` @@ -571,14 +569,14 @@ The `call` stage, such as calling `transfer`: From the wasm backtrace, it is very obvious that the execution process is ```bash - call -> deny_payment -> expect +call -> deny_payment -> expect ``` According to the code expanded macro (`cd ink/examples/erc20; cargo expand> tmp.rs`), we can see: ```bash #[no_mangle] -fn call() -> u32 { + fn call() -> u32 { if true { ::ink_lang::deny_payment::<::Env>() .expect("caller transferred value even though all ink! message deny payments") diff --git a/doc/imgs/call_other_1.png b/doc/imgs/call_other_1.png new file mode 100644 index 0000000..ffe6135 Binary files /dev/null and b/doc/imgs/call_other_1.png differ diff --git a/doc/imgs/call_other_2.png b/doc/imgs/call_other_2.png new file mode 100644 index 0000000..d0222cf Binary files /dev/null and b/doc/imgs/call_other_2.png differ