Format markdown files

Author: webmaster128

Building.md

@@ -1,7 +1,7 @@
 # Building WebAssembly Smart Contracts
 
-The subdirectories are various examples of compiling smart contracts.
-Here are some tips useful for creating your own.
+The subdirectories are various examples of compiling smart contracts. Here are
+some tips useful for creating your own.
 
 ## Setup
 
@@ -13,27 +13,29 @@ via `cargo new --lib sample`. Then add the following to `Cargo.toml`:
 crate-type = ["cdylib", "rlib"]
 ```
 
-The `cdylib` is needed for the wasm target.
-The `rlib` is needed to compile artifacts for integration tests (and benchmarking).
+The `cdylib` is needed for the wasm target. The `rlib` is needed to compile
+artifacts for integration tests (and benchmarking).
 
 **Note** throughout this demo I will use the name `hackatom` for the project.
-Please replace it with the real name of your crate. I intentionally didn't use `<name>`,
-so you can cut and paste for a quick demo. Just update this when making real code.
+Please replace it with the real name of your crate. I intentionally didn't use
+`<name>`, so you can cut and paste for a quick demo. Just update this when
+making real code.
 
 ## Requirements
 
 You must support the rust target `wasm32-unknown-unknown`.
 
-Check which ones you currently have installed via `rustup target list --installed`.
-If wasm32 is not on that list, install using `rustup target add wasm32-unknown-unknown`
-
+Check which ones you currently have installed via
+`rustup target list --installed`. If wasm32 is not on that list, install using
+`rustup target add wasm32-unknown-unknown`
 
 ## Building
 
 Go into the subdirectory, called `sample` from now on:
 
-To compile the code, run  `cargo build --release --target wasm32-unknown-unknown`.
-The output will be in `target/wasm32-unknown-unknown/release/hackatom.wasm`
+To compile the code, run
+`cargo build --release --target wasm32-unknown-unknown`. The output will be in
+`target/wasm32-unknown-unknown/release/hackatom.wasm`
 
 You probably don't want to explicitly set the target every time, so you can just
 add the following to `.cargo/config`:
@@ -43,11 +45,14 @@ add the following to `.cargo/config`:
 wasm = "build --release --target wasm32-unknown-unknown"
 ```
 
-And you can now just call `cargo wasm` to build it, and `cargo test` to run tests.
+And you can now just call `cargo wasm` to build it, and `cargo test` to run
+tests.
 
-**Note** Using `build.target` seems to force tests to use that target as well, remove this or find a work-around.
+**Note** Using `build.target` seems to force tests to use that target as well,
+remove this or find a work-around.
 [This discussion](https://internals.rust-lang.org/t/set-default-target-for-cargo-build-but-not-for-cargo-test/9777)
-and [closed PR](https://github.com/rust-lang/cargo/pull/6825) seem to suggest this will never be done.
+and [closed PR](https://github.com/rust-lang/cargo/pull/6825) seem to suggest
+this will never be done.
 
 ## Optimizations
 
@@ -56,9 +61,9 @@ Here are some things to make it smaller.
 
 ### Smaller builds
 
-If you want to request the compiler to make smaller binaries,
-you can hit a few flags (which raise compile time significantly).
-Try adding this custom profile to Cargo.toml:
+If you want to request the compiler to make smaller binaries, you can hit a few
+flags (which raise compile time significantly). Try adding this custom profile
+to Cargo.toml:
 
 ```yaml
 [profile.release]
@@ -73,19 +78,20 @@ incremental = false
 overflow-checks = true
 ```
 
-**IMPORTANT** it is essential that codegen-units is set to 1 for deterministic builds.
-Otherwise, you will have a different wasm output with each compile.
+**IMPORTANT** it is essential that codegen-units is set to 1 for deterministic
+builds. Otherwise, you will have a different wasm output with each compile.
 
 ## Shrinking the output
 
 After compiling your contract, take a look at the size of the original output:
-`du -sh  target/wasm32-unknown-unknown/release/hackatom.wasm`, it is likely around 1.5 MB.
-Most of that is unneeded and can easily be trimmed. The first approach is to use
-[`wasm-pack`](https://github.com/rustwasm/wasm-pack) to build it.
-This is designed for exporting small wasm builds and js bindings for the web, but is
-also the most actively maintained stack for trimmed wasm builds with rust.
-[`wasm-gc`](https://github.com/alexcrichton/wasm-gc), the older alternative, has
-been deprecated for this approach. (Note you must [install wasm-pack first](https://rustwasm.github.io/wasm-pack/installer/)):
+`du -sh target/wasm32-unknown-unknown/release/hackatom.wasm`, it is likely
+around 1.5 MB. Most of that is unneeded and can easily be trimmed. The first
+approach is to use [`wasm-pack`](https://github.com/rustwasm/wasm-pack) to build
+it. This is designed for exporting small wasm builds and js bindings for the
+web, but is also the most actively maintained stack for trimmed wasm builds with
+rust. [`wasm-gc`](https://github.com/alexcrichton/wasm-gc), the older
+alternative, has been deprecated for this approach. (Note you must
+[install wasm-pack first](https://rustwasm.github.io/wasm-pack/installer/)):
 
 ```sh
 cargo wasm
@@ -96,10 +102,9 @@ du -h pkg/hackatom_bg.wasm
 ```
 
 A bit smaller, huh? For the sample contract, this is around 64kB, but this
-varies a lot contract-by-contract.
-If you have plenty of dependencies and this is still too big,
-you can do a bit of investigation of where the size comes from, and maybe
-change your dependencies:
+varies a lot contract-by-contract. If you have plenty of dependencies and this
+is still too big, you can do a bit of investigation of where the size comes
+from, and maybe change your dependencies:
 
 ```sh
 cargo install twiggy
@@ -118,14 +123,15 @@ wasm-nm -i contract.wasm
 
 ## Ultra-Compression
 
-You can still get a bit smaller. Note the symbol names that were used in twiggy. Well,
-those come from inside the wasm build. You can strip out these symbols and other debug
-info, that won't be usable when running anyway. For this we use `wasm-opt` from the
-[enscripten toolchain](). This is a bunch of C++ code that needs to be compiled, and to
-simplify the whole process, as well as create reproduceable builds, we have created
-[`cosmwasm-opt`](https://github.com/confio/cosmwasm-opt),
-which contains a `Dockerfile` that you can use to run both `wasm-pack` and `wasm-opt`.
-To make the build, just run the following in the project directory:
+You can still get a bit smaller. Note the symbol names that were used in twiggy.
+Well, those come from inside the wasm build. You can strip out these symbols and
+other debug info, that won't be usable when running anyway. For this we use
+`wasm-opt` from the [enscripten toolchain](). This is a bunch of C++ code that
+needs to be compiled, and to simplify the whole process, as well as create
+reproduceable builds, we have created
+[`cosmwasm-opt`](https://github.com/confio/cosmwasm-opt), which contains a
+`Dockerfile` that you can use to run both `wasm-pack` and `wasm-opt`. To make
+the build, just run the following in the project directory:
 
 ```sh
 docker run --rm -u $(id -u):$(id -g) -v $(pwd):/code confio/cosmwasm-opt:0.4.1
@@ -134,14 +140,15 @@ du -h contract.wasm
 ```
 
 Note that this always outputs the file as `contract.wasm`, not with the name of
-the project (yes, every tool chain has a different output location).
-For the hackatom sample, I now get down to 52kB, an 18% improvement.
-This is as far as you can minimize the input, without removing actual functionality.
+the project (yes, every tool chain has a different output location). For the
+hackatom sample, I now get down to 52kB, an 18% improvement. This is as far as
+you can minimize the input, without removing actual functionality.
 
-While we cannot trim down the wasm code anymore, we can still reduce the size a bit
-for loading in blockchain transactions. We [soon plan](https://github.com/confio/go-cosmwasm/issues/20)
-to allow gzip-ed wasm in the transactions posted to the chain, which will further
-reduce gas cost of the code upload. Check out this final output:
+While we cannot trim down the wasm code anymore, we can still reduce the size a
+bit for loading in blockchain transactions. We
+[soon plan](https://github.com/confio/go-cosmwasm/issues/20) to allow gzip-ed
+wasm in the transactions posted to the chain, which will further reduce gas cost
+of the code upload. Check out this final output:
 
 ```sh
 $ gzip -k contract.wasm
@@ -152,7 +159,5 @@ $ du -h contract.wasm*
 
 And there you have it. We have gone from 1.5MB for the naive build, to 72kB with
 the standard minification tooling, all the way down to 20kB with very aggressive
-trimming and compression. Less than 1.5% of the original size. This is indeed something
-you can easily fit inside a transaction.
-
-
+trimming and compression. Less than 1.5% of the original size. This is indeed
+something you can easily fit inside a transaction.

EntryPoints.md

@@ -1,6 +1,6 @@
 # Defining Entry Points to Wasm
 
-## Exports 
+## Exports
 
 `exports` are the functions that we export to the outside world. After
 compilation these will be the only entry points that the application can call
@@ -14,18 +14,19 @@ To make an export in rust code, you can add the following lines:
 pub extern "C" fn double(n: i32) -> i32 {
     n * 2
 }
-``` 
+```
 
 Note that you need the `#[no_mangle]` directive to keep the naming, and declare
 it as `pub extern "C"` to create a proper C ABI, which is the standard interface
 for Web Assembly, as well as FFI.
 
 ## Imports
 
-If we want to interact with the outside world, the smart contract needs to define
-a set of `imports`. These are function signatures we expect to be implemented by
-the environment and provided when the VM is instantiated. If the proper imports
-are not provided, you will receive an error upon instantiating the contract. 
+If we want to interact with the outside world, the smart contract needs to
+define a set of `imports`. These are function signatures we expect to be
+implemented by the environment and provided when the VM is instantiated. If the
+proper imports are not provided, you will receive an error upon instantiating
+the contract.
 
 ```rust
 extern "C" {
@@ -34,20 +35,22 @@ extern "C" {
 }
 ```
 
-The above expects the runtime to provide read/write access to some
-(persistent) singleton. Notably, the contract has no knowledge how it is stored,
-and no way to "jailbreak" or access other element of the database.
+The above expects the runtime to provide read/write access to some (persistent)
+singleton. Notably, the contract has no knowledge how it is stored, and no way
+to "jailbreak" or access other element of the database.
 
 ## Memory Management
 
-If you look closely, you will see every function definition in `exports` accepts 
-a fixed number of arguments of type `i32` and returns one result of type `i32` (or `void`).
-With such limitations, how can one pass in a `struct` to the contract, or even
-a serialized byte array (eg. json blob). And how can we return a string back?
+If you look closely, you will see every function definition in `exports` accepts
+a fixed number of arguments of type `i32` and returns one result of type `i32`
+(or `void`). With such limitations, how can one pass in a `struct` to the
+contract, or even a serialized byte array (eg. json blob). And how can we return
+a string back?
 
 There is one more way in which the runtime can interact with a smart contract
 instance. It can directly read and write to the linear memory of the smart
-contract. In general, contracts are expected to export two well-defined functions:
+contract. In general, contracts are expected to export two well-defined
+functions:
 
 ```rust
 #[no_mangle]
@@ -66,15 +69,15 @@ pub extern "C" fn deallocate(pointer: *mut c_void, capacity: usize) {
 }
 ```
 
-`allocate` heap allocates `size` bytes and tells the wasm alloc library not to clear it
-(forget), after which it returns the pointer (integer offset) to the caller.
-The caller can now safely write up to `size` bytes to the given offset, eg.
-`copy(data, vm.Memory[offset:offset+size])`. Of course, this passes the responsibility
-of freeing the memory from the wasm code to the caller, so make sure to
-call `deallocate()` on the memory reference after the function call finishes.
+`allocate` heap allocates `size` bytes and tells the wasm alloc library not to
+clear it (forget), after which it returns the pointer (integer offset) to the
+caller. The caller can now safely write up to `size` bytes to the given offset,
+eg. `copy(data, vm.Memory[offset:offset+size])`. Of course, this passes the
+responsibility of freeing the memory from the wasm code to the caller, so make
+sure to call `deallocate()` on the memory reference after the function call
+finishes.
 
 We can explore more complex and idiomatic ways of passing data between the
-environment and the wasm contract, but for now, just ensure you export these
-two functions and the runtime will make use of them to get `string` and `[]byte`
+environment and the wasm contract, but for now, just ensure you export these two
+functions and the runtime will make use of them to get `string` and `[]byte`
 into and out of the wasm contract.
-