Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/paritytech/adz


https://github.com/paritytech/adz

Last synced: 10 months ago
JSON representation

Awesome Lists containing this project

README 

          
# TLDR

### Build 

`cargo build`

### Run Local Chain

`./target/debug/node-template --dev --tmp`

### Build Chain Spec

`./target/debug/node-template build-spec`



# Adz Demoe

### Using Nix



Install [nix](https://nixos.org/) and optionally [direnv](https://github.com/direnv/direnv) and [lorri](https://github.com/target/lorri) for a fully plug

and play experience for setting up the development environment. To get all the correct dependencies activate direnv `direnv allow` and lorri `lorri shell`.



### Rust Setup



First, complete the [basic Rust setup instructions](./docs/rust-setup.md).



### Run



Use Rust's native `cargo` command to build and launch the template node:



```sh

cargo run --release -- --dev --tmp

```



### Build



The `cargo run` command will perform an initial build. Use the following command to build the node

without launching it:



```sh

cargo build --release

```



> NOTE: You _must_ use the release builds for parachains! The optimizations here are required

> as in debug mode, it is expected that nodes are not able to run fast enough to produce blocks.



## Relay Chain



> **NOTE**: In the following two sections, we document how to manually start a few relay chain

> nodes, start a parachain node (collator), and register the parachain with the relay chain.

>

> We also have the [**`polkadot-launch`**](https://www.npmjs.com/package/polkadot-launch) CLI tool

> that automate the following steps and help you easily launch relay chains and parachains. However

> it is still good to go through the following procedures once to understand the mechanism for running

> and registering a parachain.



Once the project has been built, the following command can be used to explore all parameters and

subcommands:



```sh

./target/release/node-template -h

```



## Run



The provided `cargo run` command will launch a temporary node and its state will be discarded after

you terminate the process. After the project has been built, there are other ways to launch the

node.



### Single-Node Development Chain



This command will start the single-node development chain with persistent state:



```bash

./target/release/node-template --dev

```



### Start Relay Chain



We need _n + 1_ full _validator_ nodes running on a relay chain to accept _n_ parachain / parathread

connections. Here we will start two relay chain nodes so we can have one parachain node connecting in

later.



From the Polkadot working directory:



```bash

./target/release/node-template purge-chain --dev

```



Start the development chain with detailed logging:



```bash

RUST_LOG=debug RUST_BACKTRACE=1 ./target/release/node-template -lruntime=debug --dev

```



### Connect with Polkadot-JS Apps Front-end



To connect to a relay chain, you must first \_reserve a `ParaId` for your parathread that will

become a parachain. To do this, you will need sufficient amount of currency on the network account

to reserve the ID.



### Multi-Node Local Testnet



If you want to see the multi-node consensus algorithm in action, refer to

[our Start a Private Network tutorial](https://substrate.dev/docs/en/tutorials/start-a-private-network/).



## Template Structure



A Substrate project such as this consists of a number of components that are spread across a few

directories.



### Node



A blockchain node is an application that allows users to participate in a blockchain network.

Substrate-based blockchain nodes expose a number of capabilities:



-   Networking: Substrate nodes use the [`libp2p`](https://libp2p.io/) networking stack to allow the

    nodes in the network to communicate with one another.

-   Consensus: Blockchains must have a way to come to

    [consensus](https://substrate.dev/docs/en/knowledgebase/advanced/consensus) on the state of the

    network. Substrate makes it possible to supply custom consensus engines and also ships with

    several consensus mechanisms that have been built on top of

    [Web3 Foundation research](https://research.web3.foundation/en/latest/polkadot/NPoS/index.html).

-   RPC Server: A remote procedure call (RPC) server is used to interact with Substrate nodes.



There are several files in the `node` directory - take special note of the following:



-   [`chain_spec.rs`](./node/src/chain_spec.rs): A

    [chain specification](https://substrate.dev/docs/en/knowledgebase/integrate/chain-spec) is a

    source code file that defines a Substrate chain's initial (genesis) state. Chain specifications

    are useful for development and testing, and critical when architecting the launch of a

    production chain. Take note of the `development_config` and `testnet_genesis` functions, which

    are used to define the genesis state for the local development chain configuration. These

    functions identify some

    [well-known accounts](https://substrate.dev/docs/en/knowledgebase/integrate/subkey#well-known-keys)

    and use them to configure the blockchain's initial state.

-   [`service.rs`](./node/src/service.rs): This file defines the node implementation. Take note of

    the libraries that this file imports and the names of the functions it invokes. In particular,

    there are references to consensus-related topics, such as the

    [longest chain rule](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#longest-chain-rule),

    the [Aura](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#aura) block authoring

    mechanism and the

    [GRANDPA](https://substrate.dev/docs/en/knowledgebase/advanced/consensus#grandpa) finality

    gadget.



After the node has been [built](#build), refer to the embedded documentation to learn more about the

capabilities and configuration parameters that it exposes:



```shell

./target/release/node-template --help

```



### Runtime



In Substrate, the terms

"[runtime](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary#runtime)" and

"[state transition function](https://substrate.dev/docs/en/knowledgebase/getting-started/glossary#stf-state-transition-function)"

are analogous - they refer to the core logic of the blockchain that is responsible for validating

blocks and executing the state changes they define. The Substrate project in this repository uses

the [FRAME](https://substrate.dev/docs/en/knowledgebase/runtime/frame) framework to construct a

blockchain runtime. FRAME allows runtime developers to declare domain-specific logic in modules

called "pallets". At the heart of FRAME is a helpful

[macro language](https://substrate.dev/docs/en/knowledgebase/runtime/macros) that makes it easy to

create pallets and flexibly compose them to create blockchains that can address

[a variety of needs](https://www.substrate.io/substrate-users/).



Review the [FRAME runtime implementation](./runtime/src/lib.rs) included in this template and note

the following:



-   This file configures several pallets to include in the runtime. Each pallet configuration is

    defined by a code block that begins with `impl $PALLET_NAME::Config for Runtime`.

-   The pallets are composed into a single runtime by way of the

    [`construct_runtime!`](https://crates.parity.io/frame_support/macro.construct_runtime.html)

    macro, which is part of the core

    [FRAME Support](https://substrate.dev/docs/en/knowledgebase/runtime/frame#support-library)

    library.



### Pallets



The runtime in this project is constructed using many FRAME pallets that ship with the

[core Substrate repository](https://github.com/paritytech/substrate/tree/master/frame) and a

template pallet that is [defined in the `pallets`](./pallets/template/src/lib.rs) directory.



A FRAME pallet is compromised of a number of blockchain primitives:



-   Storage: FRAME defines a rich set of powerful

    [storage abstractions](https://substrate.dev/docs/en/knowledgebase/runtime/storage) that makes

    it easy to use Substrate's efficient key-value database to manage the evolving state of a

    blockchain.

-   Dispatchables: FRAME pallets define special types of functions that can be invoked (dispatched)

    from outside of the runtime in order to update its state.

-   Events: Substrate uses [events](https://substrate.dev/docs/en/knowledgebase/runtime/events) to

    notify users of important changes in the runtime.b

-   Errors: When a dispatchable fails, it returns an error.

-   Config: The `Config` configuration interface is used to define the types and parameters upon

    which a FRAME pallet depends.



### Run in Docker



First, install [Docker](https://docs.docker.com/get-docker/) and

[Docker Compose](https://docs.docker.com/compose/install/).



Then run the following command to start a single node development chain.



```bash

./scripts/docker_run.sh

```



This command will firstly compile your code, and then start a local development network. You can

also replace the default command (`cargo build --release && ./target/release/node-template --dev --ws-external`)

by appending your own. A few useful ones are as follow.



```bash

# Run Substrate node without re-compiling

./scripts/docker_run.sh ./target/release/node-template --dev --ws-external



# Purge the local dev chain

./scripts/docker_run.sh ./target/release/node-template purge-chain --dev



Now that you have two relay chain nodes, and a parachain node accompanied with a relay chain light

client running, the next step is to register the parachain in the relay chain with the following

steps (for detail, refer to the [Substrate Cumulus Worship](https://substrate.dev/cumulus-workshop/#/en/3-parachains/2-register)):



-   Goto [Polkadot Apps UI](https://polkadot.js.org/apps/#/explorer), connecting to your relay chain.



-   Execute a sudo extrinsic on the relay chain by going to `Developer` -> `sudo` page.



-   Pick `paraSudoWrapper` -> `sudoScheduleParaInitialize(id, genesis)` as the extrinsic type,

    shown below.



        ![Polkadot Apps UI](docs/assets/ss01.png)



-   Set the `id: ParaId` to 2,000 (or whatever ParaId you used above), and set the `parachain: Bool`

    option to **Yes**.



-   For the `genesisHead`, drag the genesis state file exported above, `para-2000-genesis`, in.



-   For the `validationCode`, drag the genesis wasm file exported above, `para-2000-wasm`, in.



> **Note**: When registering to the public Rococo testnet, ensure you set a **unique** `paraId`

> larger than 1,000. Values below 1,000 are reserved _exclusively_ for system parachains.



### Restart the Parachain (Collator)



The collator node may need to be restarted to get it functioning as expected. After a

[new epoch](https://wiki.polkadot.network/docs/en/glossary#epoch) starts on the relay chain,

your parachain will come online. Once this happens, you should see the collator start

reporting _parachain_ blocks:



```bash

# Notice the relay epoch change! Only then do we start parachain collating!

#

2021-05-30 17:00:04 [Relaychain] 💤 Idle (2 peers), best: #30 (0xfc02…2a2a), finalized #28 (0x10ff…6539), ⬇ 1.0kiB/s ⬆ 0.3kiB/s

2021-05-30 17:00:04 [Parachain] 💤 Idle (0 peers), best: #0 (0xd42b…f271), finalized #0 (0xd42b…f271), ⬇ 0 ⬆ 0

2021-05-30 17:00:06 [Relaychain] 👶 New epoch 3 launching at block 0x68bc…0605 (block slot 270402601 >= start slot 270402601).

2021-05-30 17:00:06 [Relaychain] 👶 Next epoch starts at slot 270402611

2021-05-30 17:00:06 [Relaychain] ✨ Imported #31 (0x68bc…0605)

2021-05-30 17:00:06 [Parachain] Starting collation. relay_parent=0x68bcc93d24a31a2c89800a56c7a2b275fe9ca7bd63f829b64588ae0d99280605 at=0xd42bb78354bc21770e3f0930ed45c7377558d2d8e81ca4d457e573128aabf271

2021-05-30 17:00:06 [Parachain] 🙌 Starting consensus session on top of parent 0xd42bb78354bc21770e3f0930ed45c7377558d2d8e81ca4d457e573128aabf271

2021-05-30 17:00:06 [Parachain] 🎁 Prepared block for proposing at 1 [hash: 0xf6507812bf60bf53af1311f775aac03869be870df6b0406b2969784d0935cb92; parent_hash: 0xd42b…f271; extrinsics (2): [0x1bf5…1d76, 0x7c9b…4e23]]

2021-05-30 17:00:06 [Parachain] 🔖 Pre-sealed block for proposal at 1. Hash now 0x80fc151d7ccf228b802525022b6de257e42388ec7dc3c1dd7de491313650ccae, previously 0xf6507812bf60bf53af1311f775aac03869be870df6b0406b2969784d0935cb92.

2021-05-30 17:00:06 [Parachain] ✨ Imported #1 (0x80fc…ccae)

2021-05-30 17:00:06 [Parachain] Produced proof-of-validity candidate. block_hash=0x80fc151d7ccf228b802525022b6de257e42388ec7dc3c1dd7de491313650ccae

2021-05-30 17:00:09 [Relaychain] 💤 Idle (2 peers), best: #31 (0x68bc…0605), finalized #29 (0xa6fa…9e16), ⬇ 1.2kiB/s ⬆ 129.9kiB/s

2021-05-30 17:00:09 [Parachain] 💤 Idle (0 peers), best: #0 (0xd42b…f271), finalized #0 (0xd42b…f271), ⬇ 0 ⬆ 0

2021-05-30 17:00:12 [Relaychain] ✨ Imported #32 (0x5e92…ba30)

2021-05-30 17:00:12 [Relaychain] Moving approval window from session 0..=2 to 0..=3

2021-05-30 17:00:12 [Relaychain] ✨ Imported #32 (0x8144…74eb)

2021-05-30 17:00:14 [Relaychain] 💤 Idle (2 peers), best: #32 (0x5e92…ba30), finalized #29 (0xa6fa…9e16), ⬇ 1.4kiB/s ⬆ 0.2kiB/s

2021-05-30 17:00:14 [Parachain] 💤 Idle (0 peers), best: #0 (0xd42b…f271), finalized #0 (0xd42b…f271), ⬇ 0 ⬆ 0

2021-05-30 17:00:18 [Relaychain] ✨ Imported #33 (0x8c30…9ccd)

2021-05-30 17:00:18 [Parachain] Starting collation. relay_parent=0x8c30ce9e6e9867824eb2aff40148ac1ed64cf464f51c5f2574013b44b20f9ccd at=0x80fc151d7ccf228b802525022b6de257e42388ec7dc3c1dd7de491313650ccae

2021-05-30 17:00:19 [Relaychain] 💤 Idle (2 peers), best: #33 (0x8c30…9ccd), finalized #30 (0xfc02…2a2a), ⬇ 0.7kiB/s ⬆ 0.4kiB/s

2021-05-30 17:00:19 [Parachain] 💤 Idle (0 peers), best: #1 (0x80fc…ccae), finalized #0 (0xd42b…f271), ⬇ 0 ⬆ 0

2021-05-30 17:00:22 [Relaychain] 👴 Applying authority set change scheduled at block #31

2021-05-30 17:00:22 [Relaychain] 👴 Applying GRANDPA set change to new set [(Public(88dc3417d5058ec4b4503e0c12ea1a0a89be200fe98922423d4334014fa6b0ee (5FA9nQDV...)), 1), (Public(d17c2d7823ebf260fd138f2d7e27d114c0145d968b5ff5006125f2414fadae69 (5GoNkf6W...)), 1)]

2021-05-30 17:00:22 [Relaychain] 👴 Imported justification for block #31 that triggers command Changing authorities, signaling voter.

2021-05-30 17:00:24 [Relaychain] ✨ Imported #34 (0x211b…febf)

2021-05-30 17:00:24 [Parachain] Starting collation. relay_parent=0x211b3c53bebeff8af05e8f283d59fe171b7f91a5bf9c4669d88943f5a42bfebf at=0x80fc151d7ccf228b802525022b6de257e42388ec7dc3c1dd7de491313650ccae

2021-05-30 17:00:24 [Parachain] 🙌 Starting consensus session on top of parent 0x80fc151d7ccf228b802525022b6de257e42388ec7dc3c1dd7de491313650ccae

2021-05-30 17:00:24 [Parachain] 🎁 Prepared block for proposing at 2 [hash: 0x10fcb3180e966729c842d1b0c4d8d2c4028cfa8bef02b909af5ef787e6a6a694; parent_hash: 0x80fc…ccae; extrinsics (2): [0x4a6c…1fc6, 0x6b84…7cea]]

2021-05-30 17:00:24 [Parachain] 🔖 Pre-sealed block for proposal at 2. Hash now 0x5087fd06b1b73d90cfc3ad175df8495b378fffbb02fea212cc9e49a00fd8b5a0, previously 0x10fcb3180e966729c842d1b0c4d8d2c4028cfa8bef02b909af5ef787e6a6a694.

2021-05-30 17:00:24 [Parachain] ✨ Imported #2 (0x5087…b5a0)

2021-05-30 17:00:24 [Parachain] Produced proof-of-validity candidate. block_hash=0x5087fd06b1b73d90cfc3ad175df8495b378fffbb02fea212cc9e49a00fd8b5a0

2021-05-30 17:00:24 [Relaychain] 💤 Idle (2 peers), best: #34 (0x211b…febf), finalized #31 (0x68bc…0605), ⬇ 1.0kiB/s ⬆ 130.1kiB/s

2021-05-30 17:00:24 [Parachain] 💤 Idle (0 peers), best: #1 (0x80fc…ccae), finalized #0 (0xd42b…f271), ⬇ 0 ⬆ 0

2021-05-30 17:00:29 [Relaychain] 💤 Idle (2 peers), best: #34 (0x211b…febf), finalized #32 (0x5e92…ba30), ⬇ 0.2kiB/s ⬆ 0.1kiB/s

2021-05-30 17:00:29 [Parachain] 💤 Idle (0 peers), best: #1 (0x80fc…ccae), finalized #0 (0xd42b…f271), ⬇ 0 ⬆ 0

2021-05-30 17:00:30 [Relaychain] ✨ Imported #35 (0xee07…38a0)

2021-05-30 17:00:34 [Relaychain] 💤 Idle (2 peers), best: #35 (0xee07…38a0), finalized #33 (0x8c30…9ccd), ⬇ 0.9kiB/s ⬆ 0.3kiB/s

2021-05-30 17:00:34 [Parachain] 💤 Idle (0 peers), best: #1 (0x80fc…ccae), finalized #1 (0x80fc…ccae), ⬇ 0 ⬆ 0

2021-05-30 17:00:36 [Relaychain] ✨ Imported #36 (0xe8ce…4af6)

2021-05-30 17:00:36 [Parachain] Starting collation. relay_parent=0xe8cec8015c0c7bf508bf3f2f82b1696e9cca078e814b0f6671f0b0d5dfe84af6 at=0x5087fd06b1b73d90cfc3ad175df8495b378fffbb02fea212cc9e49a00fd8b5a0

2021-05-30 17:00:39 [Relaychain] 💤 Idle (2 peers), best: #36 (0xe8ce…4af6), finalized #33 (0x8c30…9ccd), ⬇ 0.6kiB/s ⬆ 0.1kiB/s

2021-05-30 17:00:39 [Parachain] 💤 Idle (0 peers), best: #2 (0x5087…b5a0), finalized #1 (0x80fc…ccae), ⬇ 0 ⬆ 0

```



**Note the delay here!** It may take some time for your relay chain to enter a new epoch.



## Rococo & Westend Relay Chain Testnets



_Is this Cumulus Parachain Template Rococo & Westend testnets compatible?_ **Yes!**



-   **Rococo** is the testnet of Kusama (join the

    [Rococo Faucet](https://matrix.to/#/#rococo-faucet:matrix.org) to get testing funds).

-   **Westend** is the testnet of Polkadot (join the

    [Westend Faucet](https://matrix.to/#/#westend_faucet:matrix.org) to get testing funds).



See the [Cumulus Workshop](https://substrate.dev/cumulus-workshop/) for the latest instructions to

register a parathread/parachain on a relay chain.



> **NOTE**: When running the relay chain and parachain, you _must_ use the _same_ tagged version of

> [Polkadot](https://github.com/paritytech/polkadot) and [Cumulus](https://github.com/paritytech/cumulus)

> so the collator would register successfully to the relay chain.

> You should test locally registering your parachain successfully before attempting to connect to

> any running relay chain network!



Find `chainspec` files to connect to live networks [here](https://github.com/paritytech/polkadot/tree/master/node/service/res).

You want to be sure to use the correct git release tag in these files, as they change from time

to time and _must_ match the live network!



These networks are under _constant development_ - so please follow the progress and update of

your parachains in lock step with the testnet changes if you wish to connect to the network. Do

join the [Parachain Technical matrix chat room](https://app.element.io/#/room/#parachain-technical:matrix.parity.io)

to ask questions and connect with the parachain building teams.



## Learn More



-   More detailed instructions to use Cumulus parachains are found in the

    [Cumulus Workshop](https://substrate.dev/cumulus-workshop/#/en/3-parachains/2-register).

-   Refer to the upstream [Substrate Node Template](https://github.com/substrate-developer-hub/substrate-node-template)

    to learn more about the structure of this project, the capabilities it encapsulates and the way in

    which those capabilities are implemented.

-   Learn more about how a parachain block is added to a finalized chain [here](https://polkadot.network/the-path-of-a-parachain-block/).