pchain_compile 0.4.3

ParallelChain Smart Contract Compile CLI - A command line tool for compiling ParallelChain Smart Contract.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# ParallelChain Mainnet Contract Compiler (pchain_compile) 

`pchain_compile` is a command line tool for reproducibly building [Rust](https://www.rust-lang.org/) code into compact, gas-efficient WebAssembly [ParallelChain Mainnet Smart Contracts](https://github.com/parallelchain-io/parallelchain-protocol/blob/master/Contracts.md).

## Pre-Requisites

`pchain_compile` compiles the ParallelChain smart contract code from Rust into a WebAssembly binary. To know more about developing ParallelChain smart contracts, visit [ParallelChain Mainnet Contract SDK](https://crates.io/crates/pchain-sdk).

By default, the compiler requires **docker** to be installed in your local machine. In detail, it pulls the [Docker Image](#using-the-pchain_compile-docker-image) from DockerHub, and starts a docker container which provides a complete environment for building WebAssembly binary. To install docker, follow the instructions in [Docker Docs](https://docs.docker.com/get-docker/).

## Installation


Download prebuilt executables from the Github [Releases page](https://github.com/parallelchain-io/pchain-compile/releases). 

Alternatively, you can install the binary crate [pchain_compile](https://crates.io/crates/pchain_compile) by [cargo install](https://doc.rust-lang.org/cargo/commands/cargo-install.html) if Rust has been installed already.

```sh
cargo install pchain_compile
```

## Build Smart Contract

Let's say your smart contract source code is in the folder `contract` under your home directory. 

```text
/home/
|- user/
   |- contract/
      |- src/
         |- lib.rs
      |- Cargo.toml
```

Run `pchain_compile` with the arguments **source** and **destination** to specify the folder of the source code and the folder for saving the result.

```sh
pchain_compile build --source /home/user/contract --destination /home/user/result
```

Once complete, the console displays message:

```text
Build process started. This could take several minutes for large contracts.

Finished compiling. ParallelChain Mainnet smart contract(s) ["contract.wasm"] are saved at (/home/user/result).
```

Your WebAssembly smart contract is now saved with file extension `.wasm` at the destination folder. 

If you are running on Windows, here is the example output:
```powershell
$ .\pchain_compile.exe build --source 'C:\Users\user\contract' --destination 'C:\Users\user\result'
Build process started. This could take several minutes for large contracts.

Finished compiling. ParallelChain Mainnet smart contract(s) ["contract.wasm"] are saved at (C:\Users\user\result).
```

To understand more about the commands and arguments, run `pchain_compile build --help`.

## Using The `pchain_compile` Docker Image

`pchain_compile` pulls a docker image from ParallelChain Lab's official DockerHub [repository](https://hub.docker.com/r/parallelchainlab/pchain_compile) for the build process. The docker image provides an environment with installed components:
- rustc: compiler for Rust.
- wasm-snip: WASM utility which removes functions that are never called at runtime.
- wasm-opt: WASM utility to load WebAssembly in text format and run Binaryen IR passes to optimize its size. For more information on Binaryen IR see [here](http://webassembly.github.io/binaryen/).

There are different tags of the docker image. They vary on the versions of the components. The table below describes the tags and their differences.

|Image Tag |rustc |wasm-snip |wasm-opt |
|:---|:---|:---|:---|
|0.4.3 | 1.77.1 | 0.4.0| 114|
|0.4.2 | 1.71.0 | 0.4.0 | 114 |
|mainnet01 | 1.66.1 | 0.4.0 | 109 |

To build a smart contract in a specific docker environment, run with argument **use-docker-tag**. For example,

```sh
pchain_compile build --source /home/user/contract --destination /home/user/result --use-docker-tag 0.4.3
```

If **use-docker-tag** is not used, the docker image tag is determined by the version of `pchain_compile`. For example, `pchain_compile` v0.4.3 will pull the docker image with tag `0.4.3`.