From 801faf15f1f6bc0b83a48c74d35238f552bc9cdf Mon Sep 17 00:00:00 2001 From: Jose Hugo De la cruz Romero Date: Thu, 13 Dec 2018 17:28:22 -0600 Subject: [PATCH 01/10] Add documentation on Binaryen and Wabt --- wasm-engines.md | 218 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 wasm-engines.md diff --git a/wasm-engines.md b/wasm-engines.md new file mode 100644 index 0000000..2ead647 --- /dev/null +++ b/wasm-engines.md @@ -0,0 +1,218 @@ +# Wasm Engines + +Binaryen and Wabt are two WebAssembly Engines which also provides a set of tools +for compiling and decompiling wasm binary files. Both are official WebAssembly Projects. + +# Binaryen + +## Getting and compiling binaryen + +Install development tools (`build-essential`) `cmake` and `make`: + +``` +sudo apt-get install build-essential cmake make +``` + +Clone the official Binaryen repository: + +``` +git clone https://github.com/WebAssembly/binaryen.git +``` + +Move to the new `binaryen` directory and run this command to build the tools: + +``` +cmake . && make +``` + +Now you have the following binaryen tools compiled in the `bin/` directory: + +- *asm2wasm*: An asm.js to WebAssembly compiler. +- *wasm2js*: A WebAssembly to Javascript compiler (experimental). +- *wasm-as*: Assembles WebAssembly in text format (s-expression format) into binary format. +- *wasm-ctor-eval*: A tool that can execute C++ global constructors ahead of time. +- *wasm-dis*: Un-assembles WebAssembly in binary format into text format. +- *wasm-emscripten-finalize*: Takes a wasm binary produced by llvm+lld and performs emscripten-specific passes over it. +- *wasm.js*: Contains Binaryen components compiled to JavaScript, including the interpreter, `asm2wasm`, the S-Expression parser, etc. +- *wasm-merge*: Combines wasm files into a single big wasm file. +- *wasm-metadce*: Performs dead code elimination (DCE) on a larger space that the wasm module is just part of. +- *wasm-opt*: Loads WebAssembly and runs Binaryen IR passes on it. +- *wasm-reduce*: Reduce a wasm file to a smaller one that has the same behavior on a given command. +- *wasm-shell*: A shell that can load and interpret WebAssembly code. + +## Using binaryen tools + +In this section we show how to use some of the binaryen tools: + +* `wasm-as`: This tools allows to compile WebAssembly Text Format (wast) to +WebAssembly Binary Format (wasm). Example: We have a file called +`contract.wast` containing this wast code: + +``` +(module + (import "ethereum" "storageStore" (func $storageStore (param i32 i32))) + (import "ethereum" "getCodeSize" (func $getCodeSize (result i32))) + (memory 1) + (export "main" (func $main)) + (export "memory" (memory 0)) + (func $main + (i32.store (i32.const 32) (call $getCodeSize)) + (call $storageStore (i32.const 0) (i32.const 32)))) +``` + +Running `./wasm-as contract.wast` will generate a `contract.wasm` file. + +* `wasm-dis`: You can take `contract.wasm` or any other `.wasm` file generated + by other compiler and convert it to WebAssembly Text format (`wast`). + Example: running `./wasm-dis contract.wasm -o new_contract.wast` will create + the following wast codee: + +``` +(module + (type $0 (func (param i32 i32))) + (type $1 (func (result i32))) + (type $2 (func)) + (import "ethereum" "storageStore" (func $fimport$0 (param i32 i32))) + (import "ethereum" "getCodeSize" (func $fimport$1 (result i32))) + (memory $0 1) + (export "main" (func $0)) + (export "memory" (memory $0)) + (func $0 (; 2 ;) (type $2) + (i32.store + (i32.const 32) + (call $fimport$1) + ) + (call $fimport$0 + (i32.const 0) + (i32.const 32) + ) + ) +) +``` + +Note it is not _exactly_ the same code we wrote in the first place, it is more +verbose as it was generated based on the wasm binary file. + +- `wasm-shell`: This tool allows you to execute wast files. + +Example: This WebAssembly program contains two functions, `main` and `sum`, +`sum` receives two parameters `$a` and `b` and returns the sum of both +parameters. `main` calls `sum` using `2` and `3` as parameter, then calls a +`wasm-shell` provided function called `$print` to show the result. + +``` +(module + (import "spectest" "print" (func $print (param i32))) + (memory 1) + (export "main" (func $main)) + (export "memory" (memory 0)) + (func $main + (call $print (call $sum (i32.const 2) (i32.const 3)))) + (func $sum (param $a i32) (param $b i32) (result i32) + (return (i32.add (get_local $a) (get_local $b))))) +``` + +You can execute this code by calling the command: `./wasm-shell --entry main +mycode.wast`, and you will get the following result: + +``` +BUILDING MODULE [line: 1] +(i32.const 5) +``` + +Note you can not execute ewasm contracts using `wasm-shell` because the +`ethereum` namespace is not provided. + +# Wabt + +## Getting and compiling wabt + +Install development tools (`build-essential`) `cmake`, `make` and `clang`: + +``` +sudo apt-get install build-essential cmake make clang +``` + +Clone the wabt repository and its submodules: + +``` +git clone --recursive https://github.com/WebAssembly/wabt.git +cd wabt +``` + +Execute `make` + +``` +make +``` + +After successfully executing this command, a new `bin` directory is creating +containing the following wabt tools: + +- *spectest-interp*: +- *wat2wasm*: Translate from WebAssembly Text format (`wast`) to the WebAssembly Binary format (`wasm`). +- *wasm2wat*: Translate from WebAssembly Binary format to WebAssembly Text format. +- *wasm2c*: Convert a WebAssembly binary file to a C source and header. +- *wasm-objdump*: Print information about a wasm binary. +- *wasm-interp*: Decode and run a WebAssembly binary file using a stack-based interpreter. +- *wat-desugar*: Parse .wast text form as supported by the spec interpreter and print "canonical" flat format. +- *wasm-opcodecnt*: Read a file in the wasm binary format, and count opcode usage for instructions. +- *wasm-strip*: Removes sections of a WebAssembly binary file. +- *wasm-validate*: Read a file in the WebAssembly binary format and validate it. + +## Using Wabt tools + +* `wat2wasm` + +Consider this ewasm contract: + +``` +(module + (import "ethereum" "storageStore" (func $storageStore (param i32 i32))) + (import "ethereum" "getCodeSize" (func $getCodeSize (result i32))) + (memory 1) + (export "main" (func $main)) + (export "memory" (memory 0)) + (func $main + (i32.store (i32.const 32) (call $getCodeSize)) + (call $storageStore (i32.const 0) (i32.const 32)))) +``` + +Running `./wat2wasm contract.wast` generates a new binary file called `contract.wasm`. + +* `wasm2wat` + +Using this tool we can decompile the wasm file back into text format: + +``` +./wasm2wat contract.wasm -o my_contract.wat +``` + +In this case we specify an output file `my_contract.wat` in order to not +overwrite the original `wast` file. + +This is the content of the new generated wast code: + +``` +(module + (type (;0;) (func (param i32 i32))) + (type (;1;) (func (result i32))) + (type (;2;) (func)) + (import "ethereum" "storageStore" (func (;0;) (type 0))) + (import "ethereum" "getCodeSize" (func (;1;) (type 1))) + (func (;2;) (type 2) + i32.const 32 + call 1 + i32.store + i32.const 0 + i32.const 32 + call 0) + (memory (;0;) 1) + (export "main" (func 2)) + (export "memory" (memory 0))) +``` + +Note this is not exactly the same code we wrote as it was generated based on the +wasm file. + + From 7afb011086629af2b11ae5bc80d45734f451b40f Mon Sep 17 00:00:00 2001 From: Jose Hugo De la cruz Romero Date: Thu, 13 Dec 2018 17:32:54 -0600 Subject: [PATCH 02/10] formatting and syntax highlight --- wasm-engines.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/wasm-engines.md b/wasm-engines.md index 2ead647..21155e0 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -44,11 +44,13 @@ Now you have the following binaryen tools compiled in the `bin/` directory: In this section we show how to use some of the binaryen tools: -* `wasm-as`: This tools allows to compile WebAssembly Text Format (wast) to +### wasm-as + +This tool allows to compile WebAssembly Text Format (wast) to WebAssembly Binary Format (wasm). Example: We have a file called `contract.wast` containing this wast code: -``` +```wast (module (import "ethereum" "storageStore" (func $storageStore (param i32 i32))) (import "ethereum" "getCodeSize" (func $getCodeSize (result i32))) @@ -62,12 +64,15 @@ WebAssembly Binary Format (wasm). Example: We have a file called Running `./wasm-as contract.wast` will generate a `contract.wasm` file. -* `wasm-dis`: You can take `contract.wasm` or any other `.wasm` file generated - by other compiler and convert it to WebAssembly Text format (`wast`). - Example: running `./wasm-dis contract.wasm -o new_contract.wast` will create - the following wast codee: +### wasm-dis + +You can take `contract.wasm` or any other `.wasm` file generated by other +compiler and convert it to WebAssembly Text format (`wast`). Example: running +`./wasm-dis contract.wasm -o new_contract.wast` will create the following wast +codee: + -``` +```wast (module (type $0 (func (param i32 i32))) (type $1 (func (result i32))) @@ -93,14 +98,16 @@ Running `./wasm-as contract.wast` will generate a `contract.wasm` file. Note it is not _exactly_ the same code we wrote in the first place, it is more verbose as it was generated based on the wasm binary file. -- `wasm-shell`: This tool allows you to execute wast files. +### wasm-shell + +This tool allows you to execute wast files. Example: This WebAssembly program contains two functions, `main` and `sum`, `sum` receives two parameters `$a` and `b` and returns the sum of both parameters. `main` calls `sum` using `2` and `3` as parameter, then calls a `wasm-shell` provided function called `$print` to show the result. -``` +```wast (module (import "spectest" "print" (func $print (param i32))) (memory 1) @@ -162,11 +169,11 @@ containing the following wabt tools: ## Using Wabt tools -* `wat2wasm` +### wat2wasm Consider this ewasm contract: -``` +```wast (module (import "ethereum" "storageStore" (func $storageStore (param i32 i32))) (import "ethereum" "getCodeSize" (func $getCodeSize (result i32))) @@ -180,7 +187,7 @@ Consider this ewasm contract: Running `./wat2wasm contract.wast` generates a new binary file called `contract.wasm`. -* `wasm2wat` +### wasm2wat Using this tool we can decompile the wasm file back into text format: @@ -193,7 +200,7 @@ overwrite the original `wast` file. This is the content of the new generated wast code: -``` +```wast (module (type (;0;) (func (param i32 i32))) (type (;1;) (func (result i32))) From 25f20b8f55a93ed28b816eb80b9722fd28dab590 Mon Sep 17 00:00:00 2001 From: Jose Hugo De la cruz Romero Date: Thu, 13 Dec 2018 22:55:34 -0600 Subject: [PATCH 03/10] formatting --- wasm-engines.md | 47 +++++++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/wasm-engines.md b/wasm-engines.md index 21155e0..d771bc8 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -27,18 +27,18 @@ cmake . && make Now you have the following binaryen tools compiled in the `bin/` directory: -- *asm2wasm*: An asm.js to WebAssembly compiler. -- *wasm2js*: A WebAssembly to Javascript compiler (experimental). -- *wasm-as*: Assembles WebAssembly in text format (s-expression format) into binary format. -- *wasm-ctor-eval*: A tool that can execute C++ global constructors ahead of time. -- *wasm-dis*: Un-assembles WebAssembly in binary format into text format. -- *wasm-emscripten-finalize*: Takes a wasm binary produced by llvm+lld and performs emscripten-specific passes over it. -- *wasm.js*: Contains Binaryen components compiled to JavaScript, including the interpreter, `asm2wasm`, the S-Expression parser, etc. -- *wasm-merge*: Combines wasm files into a single big wasm file. -- *wasm-metadce*: Performs dead code elimination (DCE) on a larger space that the wasm module is just part of. -- *wasm-opt*: Loads WebAssembly and runs Binaryen IR passes on it. -- *wasm-reduce*: Reduce a wasm file to a smaller one that has the same behavior on a given command. -- *wasm-shell*: A shell that can load and interpret WebAssembly code. +- **asm2wasm**: An asm.js to WebAssembly compiler. +- **wasm2js**: A WebAssembly to Javascript compiler (experimental). +- **wasm-as**: Assembles WebAssembly in text format (s-expression format) into binary format. +- **wasm-ctor-eval**: A tool that can execute C++ global constructors ahead of time. +- **wasm-dis**: Un-assembles WebAssembly in binary format into text format. +- **wasm-emscripten-finalize**: Takes a wasm binary produced by llvm+lld and performs emscripten-specific passes over it. +- **wasm.js**: Contains Binaryen components compiled to JavaScript, including the interpreter, `asm2wasm`, the S-Expression parser, etc. +- **wasm-merge**: Combines wasm files into a single big wasm file. +- **wasm-metadce**: Performs dead code elimination (DCE) on a larger space that the wasm module is just part of. +- **wasm-opt**: Loads WebAssembly and runs Binaryen IR passes on it. +- **wasm-reduce**: Reduce a wasm file to a smaller one that has the same behavior on a given command. +- **wasm-shell**: A shell that can load and interpret WebAssembly code. ## Using binaryen tools @@ -156,16 +156,16 @@ make After successfully executing this command, a new `bin` directory is creating containing the following wabt tools: -- *spectest-interp*: -- *wat2wasm*: Translate from WebAssembly Text format (`wast`) to the WebAssembly Binary format (`wasm`). -- *wasm2wat*: Translate from WebAssembly Binary format to WebAssembly Text format. -- *wasm2c*: Convert a WebAssembly binary file to a C source and header. -- *wasm-objdump*: Print information about a wasm binary. -- *wasm-interp*: Decode and run a WebAssembly binary file using a stack-based interpreter. -- *wat-desugar*: Parse .wast text form as supported by the spec interpreter and print "canonical" flat format. -- *wasm-opcodecnt*: Read a file in the wasm binary format, and count opcode usage for instructions. -- *wasm-strip*: Removes sections of a WebAssembly binary file. -- *wasm-validate*: Read a file in the WebAssembly binary format and validate it. +- **wat2wasm**: Translate from WebAssembly Text format (`wast`) to the WebAssembly Binary format (`wasm`). +- **wasm2wat**: Translate from WebAssembly Binary format to WebAssembly Text format. +- **wasm2c**: Convert a WebAssembly binary file to a C source and header. +- **wasm-objdump**: Print information about a wasm binary. +- **wasm-interp**: Decode and run a WebAssembly binary file using a stack-based interpreter. +- **wat-desugar**: Parse .wast text form as supported by the spec interpreter and print "canonical" flat format. +- **wasm-opcodecnt**: Read a file in the wasm binary format, and count opcode usage for instructions. +- **wasm-strip**: Removes sections of a WebAssembly binary file. +- **wasm-validate**: Read a file in the WebAssembly binary format and validate it. +- **spectest-interp**: Read a Spectest JSON file, and run its tests in the interpreter. ## Using Wabt tools @@ -219,7 +219,6 @@ This is the content of the new generated wast code: (export "memory" (memory 0))) ``` -Note this is not exactly the same code we wrote as it was generated based on the +Note this is not _exactly_ the same code we wrote as it was generated based on the wasm file. - From 92272b46adcae1e639148c37ab2f94f3743fd0c4 Mon Sep 17 00:00:00 2001 From: Lane Rettig Date: Fri, 14 Dec 2018 15:30:22 +0700 Subject: [PATCH 04/10] Minor cleanup --- wasm-engines.md | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/wasm-engines.md b/wasm-engines.md index d771bc8..0ae59c5 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -66,12 +66,11 @@ Running `./wasm-as contract.wast` will generate a `contract.wasm` file. ### wasm-dis -You can take `contract.wasm` or any other `.wasm` file generated by other +You can take `contract.wasm` or any other `.wasm` file generated by another compiler and convert it to WebAssembly Text format (`wast`). Example: running `./wasm-dis contract.wasm -o new_contract.wast` will create the following wast -codee: +code: - ```wast (module (type $0 (func (param i32 i32))) @@ -96,15 +95,15 @@ codee: ``` Note it is not _exactly_ the same code we wrote in the first place, it is more -verbose as it was generated based on the wasm binary file. +verbose and the variable names have changed as it was generated based on the wasm binary file. ### wasm-shell This tool allows you to execute wast files. -Example: This WebAssembly program contains two functions, `main` and `sum`, +Example: This WebAssembly program contains two functions, `main` and `sum`. `sum` receives two parameters `$a` and `b` and returns the sum of both -parameters. `main` calls `sum` using `2` and `3` as parameter, then calls a +parameters. `main` calls `sum` using `2` and `3` as parameters, then calls a `wasm-shell` provided function called `$print` to show the result. ```wast @@ -127,7 +126,7 @@ BUILDING MODULE [line: 1] (i32.const 5) ``` -Note you can not execute ewasm contracts using `wasm-shell` because the +Note that you cannot currently execute ewasm contracts using `wasm-shell` because the `ethereum` namespace is not provided. # Wabt @@ -153,7 +152,7 @@ Execute `make` make ``` -After successfully executing this command, a new `bin` directory is creating +After successfully executing this command, a new `bin` directory is created containing the following wabt tools: - **wat2wasm**: Translate from WebAssembly Text format (`wast`) to the WebAssembly Binary format (`wasm`). @@ -171,6 +170,8 @@ containing the following wabt tools: ### wat2wasm +Similar to `wasm-as`, above, `wat2wasm` can be used to compile wast code to a wasm binary. + Consider this ewasm contract: ```wast @@ -189,7 +190,7 @@ Running `./wat2wasm contract.wast` generates a new binary file called `contract. ### wasm2wat -Using this tool we can decompile the wasm file back into text format: +Similar to `wasm-dis`, above, this tool allows us to decompile the wasm file back into text format: ``` ./wasm2wat contract.wasm -o my_contract.wat @@ -219,6 +220,4 @@ This is the content of the new generated wast code: (export "memory" (memory 0))) ``` -Note this is not _exactly_ the same code we wrote as it was generated based on the -wasm file. - +As with `wasm-dis`, note this is not _exactly_ the same code we wrote as it was generated based on the wasm binary file. From 60f7333d93808c1c6dc704d45305d9bf4f296856 Mon Sep 17 00:00:00 2001 From: Jose Hugo De la cruz Romero Date: Fri, 14 Dec 2018 18:30:25 -0600 Subject: [PATCH 05/10] link to already existing documentation, add a description about binaryen and wabt --- README.md | 13 ++++++++++++ wasm-engines.md | 54 ++++++++++++++++++------------------------------- 2 files changed, 33 insertions(+), 34 deletions(-) diff --git a/README.md b/README.md index 8f31a7f..3664805 100644 --- a/README.md +++ b/README.md @@ -99,6 +99,19 @@ If you're interested in adding support for another language, framework, or tools The testnet currently only supports the [go-ethereum](https://github.com/ethereum/go-ethereum) (geth) client. Support for aleth (formerly, cpp-ethereum) is a work in progress and more information may be found [here](aleth.md). +### Deploying contracts to the testnet + +Ewasm contracts can be deployed using [ewasm +studio](http://ewasm.ethereum.org/studio/), ewasm studio requires the contract +code in WebAssembly Text Format, [this guide](./wasm-engines.md) explains how to +use Binaryen or Wabt to disassemble WebAssembly Binary Format (`wasm`) into +WebAssembly Text Format (`wast`). + +Once the contract is in `wast` format you can deploy it using ewasm studio, in +order to do that the fiel `Destination Address` has to be blank, set any +value in the `Value (Wei)` field and paste the `wast` code in the `Contract Code +(WAST)` field. + ## Adding a node to the testnet ### Geth diff --git a/wasm-engines.md b/wasm-engines.md index 0ae59c5..1064392 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -1,13 +1,25 @@ # Wasm Engines -Binaryen and Wabt are two WebAssembly Engines which also provides a set of tools -for compiling and decompiling wasm binary files. Both are official WebAssembly Projects. +Binaryen and Wabt are two official WebAssembly Projects providing a set of tool +to interact with WebAssembly. + +Wabt's focus is on the manipulation of WebAssembly binary files (`wasm`) and +text format (`wast`) and conversion between the two formats. Binaryen provides a +compiler and toolchain infrastructure library for WebAssembly. It aims to make +compiling to WebAssembly ewasy, provides a C API, internal IR, and optimizer, as +Wabt, Binaryen also provides a set of tools to interact with WebAssembly binary +files and WebAssembly in Text Format. + +Currently [Hera](https://github.com/ewasm/hera) provides support for both +WebAssembly Engines, being Binaryen the one with complete support and provided +by default in Hera. # Binaryen ## Getting and compiling binaryen -Install development tools (`build-essential`) `cmake` and `make`: +Make sure development tools are already installed (cmake, make, C++ compiler), +instructions can be found [here](./README.md#manual-configuration). ``` sudo apt-get install build-essential cmake make @@ -25,20 +37,11 @@ Move to the new `binaryen` directory and run this command to build the tools: cmake . && make ``` -Now you have the following binaryen tools compiled in the `bin/` directory: +Now you have the following binaryen tools compiled in the `bin/` directory, A +description of each tool can be found +[here](https://github.com/WebAssembly/binaryen#tools). -- **asm2wasm**: An asm.js to WebAssembly compiler. -- **wasm2js**: A WebAssembly to Javascript compiler (experimental). -- **wasm-as**: Assembles WebAssembly in text format (s-expression format) into binary format. -- **wasm-ctor-eval**: A tool that can execute C++ global constructors ahead of time. -- **wasm-dis**: Un-assembles WebAssembly in binary format into text format. -- **wasm-emscripten-finalize**: Takes a wasm binary produced by llvm+lld and performs emscripten-specific passes over it. -- **wasm.js**: Contains Binaryen components compiled to JavaScript, including the interpreter, `asm2wasm`, the S-Expression parser, etc. -- **wasm-merge**: Combines wasm files into a single big wasm file. -- **wasm-metadce**: Performs dead code elimination (DCE) on a larger space that the wasm module is just part of. -- **wasm-opt**: Loads WebAssembly and runs Binaryen IR passes on it. -- **wasm-reduce**: Reduce a wasm file to a smaller one that has the same behavior on a given command. -- **wasm-shell**: A shell that can load and interpret WebAssembly code. +More information on how to build binaryen can be found in the [original repository](https://github.com/WebAssembly/binaryen#building). ## Using binaryen tools @@ -133,12 +136,6 @@ Note that you cannot currently execute ewasm contracts using `wasm-shell` becaus ## Getting and compiling wabt -Install development tools (`build-essential`) `cmake`, `make` and `clang`: - -``` -sudo apt-get install build-essential cmake make clang -``` - Clone the wabt repository and its submodules: ``` @@ -153,18 +150,7 @@ make ``` After successfully executing this command, a new `bin` directory is created -containing the following wabt tools: - -- **wat2wasm**: Translate from WebAssembly Text format (`wast`) to the WebAssembly Binary format (`wasm`). -- **wasm2wat**: Translate from WebAssembly Binary format to WebAssembly Text format. -- **wasm2c**: Convert a WebAssembly binary file to a C source and header. -- **wasm-objdump**: Print information about a wasm binary. -- **wasm-interp**: Decode and run a WebAssembly binary file using a stack-based interpreter. -- **wat-desugar**: Parse .wast text form as supported by the spec interpreter and print "canonical" flat format. -- **wasm-opcodecnt**: Read a file in the wasm binary format, and count opcode usage for instructions. -- **wasm-strip**: Removes sections of a WebAssembly binary file. -- **wasm-validate**: Read a file in the WebAssembly binary format and validate it. -- **spectest-interp**: Read a Spectest JSON file, and run its tests in the interpreter. +containing the wabt tools. A description of the wabt tools can be found [here](https://github.com/WebAssembly/wabt#wabt-the-webassembly-binary-toolkit). ## Using Wabt tools From 195fc5c0038f1c004fe58d1fa34135f3d8a6a012 Mon Sep 17 00:00:00 2001 From: Lane Rettig Date: Sat, 15 Dec 2018 15:05:40 +0700 Subject: [PATCH 06/10] Minor cleanup Move into the "smart contracts" section --- README.md | 19 ++++++------------- 1 file changed, 6 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 3664805..624f5e4 100644 --- a/README.md +++ b/README.md @@ -54,7 +54,7 @@ You don't need any special infrastructure to transact on the Ewasm testnet. You Voila! You're now ready to transact on the testnet. -## Writing and compiling smart contracts +## Writing, compiling, and deploying smart contracts ### Solidity/EVM @@ -95,22 +95,15 @@ At present, we've developed support for the following languages and toolchains: If you're interested in adding support for another language, framework, or toolset, see the Contributing section above and reach out. -## Running a testnet node locally +### Deploying contracts to the testnet -The testnet currently only supports the [go-ethereum](https://github.com/ethereum/go-ethereum) (geth) client. Support for aleth (formerly, cpp-ethereum) is a work in progress and more information may be found [here](aleth.md). +Ewasm contracts can be deployed using [ewasm studio](http://ewasm.ethereum.org/studio/), which requires the contract code in WebAssembly Text Format. If you want to deploy a Wasm binary, [this guide](./wasm-engines.md) explains how to use Binaryen or Wabt to disassemble WebAssembly Binary Format (`wasm`) into WebAssembly Text Format (`wast`). -### Deploying contracts to the testnet +Once the contract is in `wast` format you can deploy it using ewasm studio: the field `Destination Address` should be blank, set any value in the `Value (Wei)` field, and paste the `wast` code in the `Contract Code (WAST)` field. Then hit "SUBMIT TRANSACTION" to deploy. -Ewasm contracts can be deployed using [ewasm -studio](http://ewasm.ethereum.org/studio/), ewasm studio requires the contract -code in WebAssembly Text Format, [this guide](./wasm-engines.md) explains how to -use Binaryen or Wabt to disassemble WebAssembly Binary Format (`wasm`) into -WebAssembly Text Format (`wast`). +## Running a testnet node locally -Once the contract is in `wast` format you can deploy it using ewasm studio, in -order to do that the fiel `Destination Address` has to be blank, set any -value in the `Value (Wei)` field and paste the `wast` code in the `Contract Code -(WAST)` field. +The testnet currently only supports the [go-ethereum](https://github.com/ethereum/go-ethereum) (geth) client. Support for aleth (formerly, cpp-ethereum) is a work in progress and more information may be found [here](aleth.md). ## Adding a node to the testnet From 34d633337c71bd9b2ac16e8eaa617c2b1fa74631 Mon Sep 17 00:00:00 2001 From: Lane Rettig Date: Sat, 15 Dec 2018 15:10:31 +0700 Subject: [PATCH 07/10] Some minor cleanup --- wasm-engines.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/wasm-engines.md b/wasm-engines.md index 1064392..12d4e20 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -1,14 +1,17 @@ # Wasm Engines -Binaryen and Wabt are two official WebAssembly Projects providing a set of tool -to interact with WebAssembly. +[Binaryen](https://github.com/WebAssembly/binaryen.git) and +[Wabt](https://github.com/WebAssembly/wabt.git) are two [official WebAssembly +Projects](https://github.com/WebAssembly/) providing a set of tools to interact +with WebAssembly. Wabt's focus is on the manipulation of WebAssembly binary files (`wasm`) and text format (`wast`) and conversion between the two formats. Binaryen provides a compiler and toolchain infrastructure library for WebAssembly. It aims to make -compiling to WebAssembly ewasy, provides a C API, internal IR, and optimizer, as -Wabt, Binaryen also provides a set of tools to interact with WebAssembly binary -files and WebAssembly in Text Format. +compiling to WebAssembly easy, provides a C API, internal IR, and optimizer. +Similar to Wabt, Binaryen also provides a set of tools to interact with +WebAssembly binary files and WebAssembly in Text Format. The rest of this +document explains how to use these tools to work with Ewasm contracts. Currently [Hera](https://github.com/ewasm/hera) provides support for both WebAssembly Engines, being Binaryen the one with complete support and provided @@ -21,10 +24,6 @@ by default in Hera. Make sure development tools are already installed (cmake, make, C++ compiler), instructions can be found [here](./README.md#manual-configuration). -``` -sudo apt-get install build-essential cmake make -``` - Clone the official Binaryen repository: ``` From e59ed255f4eafc13b29bef31cf81691e5f23e869 Mon Sep 17 00:00:00 2001 From: Lane Rettig Date: Sat, 15 Dec 2018 15:13:35 +0700 Subject: [PATCH 08/10] Clarify info on hera engine support --- wasm-engines.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/wasm-engines.md b/wasm-engines.md index 12d4e20..8951713 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -13,9 +13,9 @@ Similar to Wabt, Binaryen also provides a set of tools to interact with WebAssembly binary files and WebAssembly in Text Format. The rest of this document explains how to use these tools to work with Ewasm contracts. -Currently [Hera](https://github.com/ewasm/hera) provides support for both -WebAssembly Engines, being Binaryen the one with complete support and provided -by default in Hera. +By default, [Hera](https://github.com/ewasm/hera) ships with binaryen support, +but it can also be compiled with wabt support. See +[build options](https://github.com/ewasm/hera#build-options) for more information. # Binaryen From 494ec1c3de622f0f8d1372d6e42c45f816f5e43e Mon Sep 17 00:00:00 2001 From: Jose Hugo De la cruz Romero Date: Mon, 17 Dec 2018 12:06:14 -0600 Subject: [PATCH 09/10] explain wabt/binaryen compatibility issues --- wasm-engines.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/wasm-engines.md b/wasm-engines.md index 8951713..33a9055 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -17,6 +17,12 @@ By default, [Hera](https://github.com/ewasm/hera) ships with binaryen support, but it can also be compiled with wabt support. See [build options](https://github.com/ewasm/hera#build-options) for more information. +Binaryen and Wabt's WebAssembly Text Format are not fully compatible with each +other, if you decompile a `wasm` contract using `wasm-dis` (Binaryen) you may +not be able to compile the resulting `wast` back to `wasm` using `wat2wasm` +(Wabt). For compatibility purposes, the same wasm engine used by Hera should be +used to generate the `wasm` or `wast` files. + # Binaryen ## Getting and compiling binaryen From 4037c97d45f9b9f1c4067394242e2f1348f9f480 Mon Sep 17 00:00:00 2001 From: Lane Rettig Date: Thu, 27 Dec 2018 08:09:06 -0500 Subject: [PATCH 10/10] Some minor tweaks Change capitalization, reformat slightly, add a link --- wasm-engines.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/wasm-engines.md b/wasm-engines.md index 33a9055..7509675 100644 --- a/wasm-engines.md +++ b/wasm-engines.md @@ -8,17 +8,19 @@ with WebAssembly. Wabt's focus is on the manipulation of WebAssembly binary files (`wasm`) and text format (`wast`) and conversion between the two formats. Binaryen provides a compiler and toolchain infrastructure library for WebAssembly. It aims to make -compiling to WebAssembly easy, provides a C API, internal IR, and optimizer. -Similar to Wabt, Binaryen also provides a set of tools to interact with -WebAssembly binary files and WebAssembly in Text Format. The rest of this -document explains how to use these tools to work with Ewasm contracts. +compiling to WebAssembly easy and provides a C API, internal IR, and optimizer. +Similar to Wabt, binaryen also provides a set of tools to interact with +WebAssembly binary files and WebAssembly in +[text format](https://github.com/WebAssembly/design/blob/master/TextFormat.md). +The rest of this document explains how to use these tools to work with Ewasm +contracts. By default, [Hera](https://github.com/ewasm/hera) ships with binaryen support, but it can also be compiled with wabt support. See [build options](https://github.com/ewasm/hera#build-options) for more information. -Binaryen and Wabt's WebAssembly Text Format are not fully compatible with each -other, if you decompile a `wasm` contract using `wasm-dis` (Binaryen) you may +Binaryen's and Wabt's WebAssembly text formats are not fully compatible with each +other, so if you decompile a `wasm` contract using `wasm-dis` (binaryen) you may not be able to compile the resulting `wast` back to `wasm` using `wat2wasm` (Wabt). For compatibility purposes, the same wasm engine used by Hera should be used to generate the `wasm` or `wast` files. @@ -27,10 +29,10 @@ used to generate the `wasm` or `wast` files. ## Getting and compiling binaryen -Make sure development tools are already installed (cmake, make, C++ compiler), -instructions can be found [here](./README.md#manual-configuration). +Make sure development tools are already installed (cmake, make, C++ compiler). +Instructions can be found [here](./README.md#manual-configuration). -Clone the official Binaryen repository: +Clone the official binaryen repository: ``` git clone https://github.com/WebAssembly/binaryen.git @@ -42,11 +44,11 @@ Move to the new `binaryen` directory and run this command to build the tools: cmake . && make ``` -Now you have the following binaryen tools compiled in the `bin/` directory, A +Now you have the following binaryen tools compiled in the `bin/` directory. A description of each tool can be found [here](https://github.com/WebAssembly/binaryen#tools). -More information on how to build binaryen can be found in the [original repository](https://github.com/WebAssembly/binaryen#building). +More information on how to build binaryen can be found in the [master repository](https://github.com/WebAssembly/binaryen#building). ## Using binaryen tools @@ -110,7 +112,7 @@ verbose and the variable names have changed as it was generated based on the was This tool allows you to execute wast files. Example: This WebAssembly program contains two functions, `main` and `sum`. -`sum` receives two parameters `$a` and `b` and returns the sum of both +`sum` receives two parameters `$a` and `$b` and returns the sum of both parameters. `main` calls `sum` using `2` and `3` as parameters, then calls a `wasm-shell` provided function called `$print` to show the result.