## Building on Substrate - general impressions

This short doc describes our experience of building on paritytech's substrate. What we built is a short module that implements the AdEx [OUTPACE](https://github.com/AdExNetwork/adex-protocol/blob/master/OUTPACE.md) payment channels. The real work took no more than a day.

This module can be used to create a parachain on [polkadot](https://polkadot.network/).

### Useful material

https://substrate.readme.io/docs/creating-a-custom-substrate-chain

https://hackmd.io/s/SJ6K_UnyV

http://github.com/paritytech/substrate - other than the README and docs, reading the modules in `srml` can save you **a ton** of time

https://wiki.parity.io/

Verifying signed messages: https://github.com/AdExNetwork/adex-protocol-substrate/blob/rebase/runtime/src/adex_outpace/mod.rs#L101

### What you need to know

First and foremost, **you need to know Rust**. Unlike other mainstream languages, which are generally similar to each other, Rust brings a few things to the table that make it look different and generally not that readable to people who haven't spent time studying it.

Due to the early stage of the substrate project, and it's heavy reliance on macros, the more Rust you know, the better.

### Our experience

There's a lot of things to lean on: the fantastic community (riot substrate-technical chat), the `srml` modules (part of the substrate repo), and the advancing documentation (see [Useful material](#useful-material)).

The biggest setback is the project's reliance on compiler macros (namely `decl_storage!` and `construct_runtime!`), which are not really well documented, and define non-standard syntax. The biggest blockers were around figuring them out. However, a lot can be learned from reading other modules in the substrate `srml/` directory.

A lot of types/traits are defined *because* of something you do in those macros.

`RUSTFLAGS="-Z external-macro-backtrace"` can also help you a lot.

Another gotcha was the accidental usage of libraries that are not available to you when you compile the runtime to WASM. For example, `Vec` is not available unless you use the `rstd` prelude. Here's a list of commits that fixed those mistakes:

https://github.com/AdExNetwork/adex-protocol-substrate/commit/3530323d5303561a41f894fcadc2905eb170afb6

https://github.com/AdExNetwork/adex-protocol-substrate/commit/af27daf5ce42fb58e0a3859fcfd1e7c65e4ef4d1

### Compared to Solidity

A lot of the headaches that will lose you time in solidity (e.g. arrays with 2 dynamic-sized dimensions, [ERC20 weirdness](https://github.com/AdExNetwork/adex-protocol-eth/blob/master/contracts/libs/SafeERC20.sol), [array shenanigans](https://delegatecall.com/questions/workaround-for-return-dynamic-array-from-solidity69924f08-a061-426f-a326-2bed3f566e53), etc.) simply do not exist in Rust. You might end up fighting the compiler for different things (borrows, trait bounds), but there's a lot less feeling of time being wasted because of immaturity.

### Conclusion

With proper documentation and usability improvements, the combination of Rust and Substrate could become the easiest, fastest and safest way to create pretty much any type of blockchain application.

### Feedback for the substrate team

* macros need more documentation, and/or more intuitive syntax; even links to various ways that macros are being used in `srml` would be great
* perhaps it would be useful to have a safeguard that doesn't allow you to put things you can't comile to WASM in your modules, even if you're compiling natively
* this is not a reasonable thing to ask for at such an early stage, but having stable APIs/interfaces would be great
* or at least keep the `substrate-node-template` up to date with the latest substrate master