darwinia-network / Darwinia

= Darwinia :Author: Darwinia developers :Revision: 0.1.0 :toc: :sectnums:

image:https://travis-ci.org/darwinia-network/darwinia.svg[Build Status (Travis CI),link=https://travis-ci.org/darwinia-network/darwinia] image:https://img.shields.io/badge/License-GPLv3-blue.svg[License: GPL v3,link=https://www.gnu.org/licenses/gpl-3.0]

== Introduction

image:https://github.com/darwinia-network/rfcs/raw/master/logo/darwinia.png[image]

Darwinia is a bridge blockchain connecting different chains using darwinia relay and can be connected to Polkadot network as a parachain.

As an open cross-chain bridge protocol based on Substrate, Darwinia focuses on the construction of future Internet of Tokens, including decentralized tokens swap, exchange, and market.

== Architecture

image:https://github.com/darwinia-network/rfcs/raw/master/RFC/zh_CN/images/0007-darwinia-architecture.jpeg[Darwinia Architecture]

It could have two models, the Solo model and the Polkadot model. For more details, go to https://github.com/darwinia-network/rfcs/blob/master/RFC/zh_CN/0007-dawinia-token-staking-model.md#solo%E6%A8%A1%E5%BC%8F[RFC-0007].

== Road Map

Darwinia Network is composed of Darwinia Bridge Chain(Darwinia), and a series of other blockchains bridged to Darwinia, including public blockchains such as Ethereum, Tron, EOS, and application specific blockchains.

Darwinia Bridge Chain will provide interoperability for cross-chain tokens using Darwinia's bridge relay innovation and decentralized backing technology.

Crab Network is a canary network for Darwinia, Darwinia's new cutting edge technologies will be first deployed on Crab Network.

For more details, go to link:ROADMAP.md[Road Map].

// === So far

// - 0.1 "PoC-1": PBFT consensus, Wasm runtime engine, basic runtime modules. // - 0.2 "PoC-2": Libp2p

// === In progress

// - AfG consensus // - Improved PoS // - Smart contract runtime module

// === The future

// - Splitting out runtime modules into separate repo // - Introduce substrate executable (the skeleton-key runtime) // - Introduce basic but extensible transaction queue and block-builder and place them in the executable. // - DAO runtime module // - Audit

// == Trying out Darwinia Node // // === On Mac and Ubuntu // // === On Windows

== Building

=== Hacking on Darwinia

If you'd actually like to hack on Darwinia, you can just grab the source code and build it. We also provide the script to help you setup your developing environment in bellow sections. Please ensure you have Rust and the support software installed:

==== Linux and Mac

For Unix-based operating systems, you should run the following commands:

[source, shell]

curl https://sh.rustup.rs -sSf | sh

rustup default nightly rustup target add wasm32-unknown-unknown

You will also need to install the following packages:

• Linux: [source, shell] sudo apt install cmake pkg-config libssl-dev git clang libclang-dev

• Linux on ARM: rust-lld is required for linking wasm, but is missing on non Tier 1 platforms. So, use this https://github.com/Plume-org/Plume/blob/master/script/wasm-deps.sh[script] to build lld and create the symlink /usr/bin/rust-lld to the build binary.

• Mac: [source, shell] brew install cmake pkg-config openssl git llvm

To finish installation of Darwinia, jump down to <<shared-steps,shared steps>>.

==== Windows

If you are trying to set up Darwinia on Windows, you should do the following:

1. First, you will need to download and install "Build Tools for Visual Studio:"

   • You can get it at this link: https://aka.ms/buildtools
   • Run the installation file: vs_buildtools.exe
   • Please ensure the Windows 10 SDK component is included when installing the Visual C++ Build Tools.
   • image:https://i.imgur.com/zayVLmu.png[image]
   • Restart your computer.

2. Next, you need to install Rust:

   • Detailed instructions are provided by the https://doc.rust-lang.org/book/ch01-01-installation.html#installing-rustup-on-windows[Rust Book].
     • Download from: https://www.rust-lang.org/tools/install
     • Run the installation file: rustup-init.exe

     Note that it should not prompt you to install vs_buildtools since you did it in step 1.

     • Choose "Default Installation."
     • To get started, you need Cargo's bin directory (%USERPROFILE%.cargo\bin) in your PATH environment variable. Future applications will automatically have the correct environment, but you may need to restart your current shell.

3. Then, you will need to run some commands in CMD to set up your Wasm Build Environment:

   rustup default nightly rustup target add wasm32-unknown-unknown

4. Then, you need to install LLVM: https://releases.llvm.org/download.html

5. Next, you need to install OpenSSL, which we will do with vcpkg:

   mkdir \Tools cd \Tools git clone https://github.com/Microsoft/vcpkg.git cd vcpkg .\bootstrap-vcpkg.bat .\vcpkg.exe install openssl:x64-windows-static

6. After, you need to add OpenSSL to your System Variables. Note that in order for the following commands to work, you need to use Windows Powershell:

   $env:OPENSSL_DIR = 'C:\Tools\vcpkg\installed\x64-windows-static' $env:OPENSSL_STATIC = 'Yes' [System.Environment]::SetEnvironmentVariable('OPENSSL_DIR', $env:OPENSSL_DIR, [System.EnvironmentVariableTarget]::User) [System.Environment]::SetEnvironmentVariable('OPENSSL_STATIC', $env:OPENSSL_STATIC, [System.EnvironmentVariableTarget]::User)

7. Finally, you need to install cmake: https://cmake.org/download/

==== Shared Steps

Then, grab the Darwinia source code:

[source, shell]

git clone https://github.com/darwinia-network/darwinia.git cd darwinia

Then build the code:

[source, shell]

cargo build # Builds all native code

You can run all the tests if you like:

[source, shell] cargo test --all

Or just run the tests of a specific package (i.e. cargo test -p darwinia-staking)

You can start a development chain with:

[source, shell] cargo run --release -- --dev

Detailed logs may be shown by running the node with the following environment variables set: RUST_LOG=debug RUST_BACKTRACE=1 cargo run --release \-- --dev.

If you want to see the multi-node consensus algorithm in action locally, then you can create a local testnet with two validator nodes for Alice and Bob, who are the initial authorities of the genesis chain specification that have been endowed with a testnet Ring.

We'll start Alice's Darwinia node first with her chain database stored locally at /tmp/darwinia-develop/alice:

[source, shell] cargo run --release --
--alice
--rpc-external
--rpc-port 23333
--ws-external
--ws-port 23334
--rpc-cors all
--port 23335
--base-path /tmp/darwinia-develop/alice

Or just:

[source, shell] cargo run --release -- --alice --conf=boot-conf/develop/alice.json

In the second terminal, we'll run the following to start Bob's Darwinia node on a different TCP port, and with his chain database stored locally at /tmp/darwinia-develop/bob:

[source, shell] cargo run --release --
--bob
--rpc-external
--rpc-port 23336
--ws-external
--ws-port 23337
--rpc-cors all
--port 23338
--base-path /tmp/darwinia-develop/bob

Or just:

[source, shell] cargo run --release -- --bob --conf=boot-conf/develop/bob.json

Additional Darwinia CLI usage options are available and may be shown by running cargo run --release -- --help.

=== WASM binaries

The WASM binaries are built during the normal cargo build process. To control the WASM binary building, we support multiple environment variables:

• SKIP_WASM_BUILD - Skips building any WASM binary. This is useful when only native should be recompiled.
• BUILD_DUMMY_WASM_BINARY - Builds dummy WASM binaries. These dummy binaries are empty and useful for cargo check runs.
• WASM_BUILD_TYPE - Sets the build type for building WASM binaries. Supported values are release or debug. By default the build type is equal to the build type used by the main build.
• TRIGGER_WASM_BUILD - Can be set to trigger a WASM build. On subsequent calls the value of the variable needs to change. As WASM builder instructs cargo to watch for file changes this environment variable should only be required in certain circumstances.
• WASM_TARGET_DIRECTORY - Will copy any build WASM binary to the given directory. The path needs to be absolute.
• WASM_BUILD_RUSTFLAGS - Extend RUSTFLAGS given to cargo build while building the wasm binary.
• WASM_BUILD_NO_COLOR - Disable color output of the wasm build.

Each project can be skipped individually by using the environment variable SKIP_PROJECT_NAME_WASM_BUILD. Where PROJECT_NAME needs to be replaced by the name of the cargo project, e.g. node-runtime will be NODE_RUNTIME.

=== Precautions

If you run into problems when building this project, please kindly check following things before making an issue.

• using the latest nightly Rust
• build without sccache

== Joining the Crab Network

// Latest known working version: ``

=== Quick start (professional):

• https://telemetry.polkadot.io/#list/Crab[Telemetry]
• https://apps.darwinia.network[Darwinia Web Wallet]
• Bootnodes List: ** /ip4/175.24.95.3/tcp/30333/p2p/12D3KooWKdcGZkFe3y63dj8VWLH6xw3rB5QhhnoC8UenSscXFuqx ** /ip4/35.234.33.88/tcp/30333/p2p/QmR4fARccJJA2o2Ac3fG2FcgatyGaoaZqUzymUDpvBZr7c ** /ip4/35.234.9.96/tcp/30333/p2p/QmPPGpFMgqSm9ZeeHubZk8UXpKdZMNRCk4Wkymm181bpve

Getting the runable darwinia binary from downloading the compiled executed binary directly or building from source code. Then, type the command below to sync Crab network: [source, shell] ./darwinia
-d /tmp/node
--bootnodes /ip4/xxx
--name node
--chain crab

=== Full tutorial (beginner):

• EN-US (not yet)
• https://talk.darwinia.network/topics/147[ZH-CN]

// [source, shell] // ---- // git clone https://github.com/paritytech/substrate.git // cd substrate // git checkout -b flaming-fir a2a0eb5398d6223e531455b4c155ef053a4a3a2b // ---- // // You can run the tests if you like: // // [source, shell] // cargo test --all // // Start your node: // // [source, shell] // cargo run --release -- // // To see a list of command line options, enter: // // [source, shell] // cargo run --release -- --help // // For example, you can choose a custom node name: // // [source, shell] // cargo run --release -- --name my_custom_name // // If you are successful, you will see your node syncing at https://telemetry.polkadot.io/#/Flaming%20Fir

== Key management

Keys in Darwinia are stored in the keystore in the file system. To store keys into this keystore, you need to use one of the two provided RPC calls. If your keys are encrypted or should be encrypted by the keystore, you need to provide the key using one of the CLI arguments --password, --password-interactive, or --password-filename.

=== Recommended RPC call

For most users who want to run a validator node, the author_rotateKeys RPC call is sufficient. The RPC call will generate N Session keys for you and return their public keys. N is the number of session keys configured in the runtime. The output of the RPC call can be used as input for the session::set_keys transaction.

curl -H 'Content-Type: application/json' --data '{ "jsonrpc":"2.0", "method":"author_rotateKeys", "id":1 }' localhost:9933

=== Advanced RPC call

If the Session keys need to match a fixed seed, they can be set individually key by key. The RPC call expects the key seed and the key type. The key types supported by default in Darwinia are listed https://github.com/paritytech/substrate/blob/master/core/primitives/src/crypto.rs#L767[here], but the user can declare any key type.

curl -H 'Content-Type: application/json' --data '{ "jsonrpc":"2.0", "method":"author_insertKey", "params":["KEY_TYPE", "SEED", "PUBLIC"],"id":1 }' localhost:9933

KEY_TYPE - needs to be replaced with the 4-character key type identifier. SEED - is the seed of the key. PUBLIC - public key for the given key.

== Documentation

=== Viewing documentation for Darwinia packages

You can generate the documentation for a Darwinia Rust package and have it automatically open in your web browser using https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html#using-rustdoc-with-cargo[rustdoc with Cargo], (of the The Rustdoc Book), by running the following command:

cargo doc --open

If you just want to generate the document from specific package, you may use the following command:

cargo doc --package <spec> --open

And replace <spec> with one of the following (i.e. cargo doc --package darwinia-cli --open):

• Darwinia Core [source, shell] darwinia-cli, ethash, fly-client, merkle-mountain-range, merkle-patricia-trie, eth-primitives
• Darwinia Runtime Module Library [source, shell] darwinia-balances, darwinia-eth-backing, darwinia-eth-relay, darwinia-staking, darwinia-support
• Node [source, shell] node-cli, node-primitives, node-runtime

== Contributing

=== Environment

The scripts/bootstrap.sh helps set up your development environment. The nightly Rust, cargo, rustfmt will be installed, the git hooks will be set, and ready to code.

Besides, the script will install some essential packages depends on your OS, if you want to do it manually, use the --fast option to skip. We will appreciate your contribution.

If you have any questions when hacking on Darwinia, feel free to let us know on the Riot room https://riot.im/app/#/group/+darwinia:matrix.org[#darwinia:matrix.org].

=== Contributing Guidelines

link:CONTRIBUTING.adoc[CONTRIBUTING.adoc]

== License

https://github.com/darwinia-network/darwinia/blob/master/LICENSE[LICENSE]