# Pezcumulus ☁️

[![Doc](https://img.shields.io/badge/pezcumulus%20docs-master-brightgreen)](https://docs.pezkuwichain.io/pezcumulus/)

This repository contains both the Pezcumulus SDK and also specific chains implemented on top of this SDK.

If you only want to run a **PezkuwiChain Teyrchain Node**, check out our [container section](../docs/contributor/container.md).

## Pezcumulus SDK

A set of tools for writing [Bizinikiwi](https://bizinikiwi.pezkuwichain.app/)-based [PezkuwiChain](https://wiki.network.pezkuwichain.io/en/)
[teyrchains](https://wiki.network.pezkuwichain.io/docs/en/learn-parachains). Refer to the included [overview](docs/overview.md)
for architectural details, and the [Connect to a relay chain how-to
guide](https://docs.pezkuwichain.io/reference/how-to-guides/parachains/connect-to-a-relay-chain/) for a guided walk-through
of using these tools.

It's easy to write blockchains using Bizinikiwi, and the overhead of writing teyrchains' distribution, p2p, database, and
synchronization layers should be just as low. This project aims to make it easy to write teyrchains for PezkuwiChain by
leveraging the power of Bizinikiwi.

Pezcumulus clouds are shaped sort of like dots; together they form a system that is intricate, beautiful and functional.

### Consensus

[`teyrchain-consensus`](https://github.com/pezkuwichain/pezkuwi-sdk/blob/master/pezcumulus/client/consensus/common/src/parachain_consensus.rs)
is a [consensus engine](https://docs.pezkuwichain.io/v3/advanced/consensus) for Bizinikiwi that follows a PezkuwiChain [relay
chain](https://wiki.network.pezkuwichain.io/docs/en/learn-architecture#relay-chain). This will run a PezkuwiChain node internally,
and dictate to the client and synchronization algorithms which chain to follow,
[finalize](https://wiki.network.pezkuwichain.io/docs/en/learn-consensus#probabilistic-vs-provable-finality), and treat as best.

### Collator

A PezkuwiChain [collator](https://wiki.network.pezkuwichain.io/docs/en/learn-collator) for the teyrchain is implemented by the
`pezkuwi-teyrchain` binary (previously called `pezkuwi-collator`).

You may run `pezkuwi-teyrchain` locally after building it or using one of the container option described
[the container setup guide](../docs/contributor/container.md).

### Relay Chain Interaction
To operate a teyrchain node, a connection to the corresponding relay chain is necessary. This can be achieved in one of
two ways:
1. Run a full relay chain node within the teyrchain node (default)
2. Connect to an external relay chain node via WebSocket RPC

#### In-process Relay Chain Node
If an external relay chain node is not specified (default behavior), then a full relay chain node is spawned within the
same process.

This node has all of the typical components of a regular PezkuwiChain node and will have to fully sync with the relay chain
to work.

##### Example command
```bash
pezkuwi-teyrchain \
	--chain teyrchain-chainspec.json \
	--tmp \
	-- \
	--chain relaychain-chainspec.json
```

#### External Relay Chain Node
An external relay chain node is connected via WebSocket RPC by using the `--relay-chain-rpc-urls` command line
argument. This option accepts one or more space-separated WebSocket URLs to a full relay chain node. By default, only
the first URL will be used, with the rest as a backup in case the connection to the first node is lost.

Teyrchain nodes using this feature won't have to fully sync with the relay chain to work, so in general they will use
fewer system resources.

**Note:** At this time, any teyrchain nodes using this feature will still spawn a significantly cut-down relay chain
node in-process. Even though they lack the majority of normal PezkuwiChain subsystems, they will still need to connect
directly to the relay chain network.

##### Example command

```bash
pezkuwi-teyrchain \
	--chain teyrchain-chainspec.json \
	--tmp \
	--relay-chain-rpc-urls \
		"ws://relaychain-rpc-endpoint:9944" \
		"ws://relaychain-rpc-endpoint-backup:9944" \
	-- \
	--chain relaychain-chainspec.json
```

## Installation and Setup
Before building Pezcumulus SDK based nodes / runtimes prepare your environment by following Bizinikiwi [installation
instructions](https://docs.pezkuwichain.io/main-docs/install/).

To launch a local network, you can use [zombienet](https://github.com/paritytech/zombienet) for quick setup and
experimentation or follow the [manual setup](#manual-setup).

### Zombienet
We use Zombienet to spin up networks for integration tests and local networks. Follow [these installation
steps](https://github.com/paritytech/zombienet#requirements-by-provider) to set it up on your machine. A simple network
specification with two relay chain nodes and one collator is located at
[zombienet/examples/small_network.toml](zombienet/examples/small_network.toml).

#### Which provider should I use?
Zombienet offers multiple providers to run networks. Choose the one that best fits your needs:
- **Podman:** Choose this if you want to spin up a network quick and easy.
- **Native:** Choose this if you want to develop and deploy your changes. Requires compilation of the binaries.
- **Kubernetes:** Choose this for advanced use-cases or running on cloud-infrastructure.

#### How to run
To run the example network, use the following commands:
```bash
# Podman provider
zombienet --provider podman spawn ./zombienet/examples/small_network.toml

# Native provider, assumes pezkuwi and pezkuwi-teyrchains binary in $PATH
zombienet --provider native spawn ./zombienet/examples/small_network.toml
```

### Manual Setup
#### Launch the Relay Chain

```bash
# Clone
git clone https://github.com/pezkuwichain/pezkuwi-sdk

# Compile PezkuwiChain's required binaries
cargo build --release -p pezkuwi

# Generate a raw chain spec
./target/release/pezkuwi build-spec --chain pezkuwichain-local --disable-default-bootnode --raw > pezkuwichain-local-cfde.json

# Alice
./target/release/pezkuwi --chain pezkuwichain-local-cfde.json --alice --tmp

# Bob (In a separate terminal)
./target/release/pezkuwi --chain pezkuwichain-local-cfde.json --bob --tmp --port 30334
```

#### Launch the Teyrchain

```bash
# Compile
cargo build --release -p pezkuwi-teyrchain-bin

# Export genesis state
./target/release/pezkuwi-teyrchain export-genesis-state > genesis-state

# Export genesis wasm
./target/release/pezkuwi-teyrchain export-genesis-wasm > genesis-wasm

# Collator1
./target/release/pezkuwi-teyrchain --collator --alice --force-authoring \
  --tmp --port 40335 --rpc-port 9946 -- --chain pezkuwichain-local-cfde.json --port 30335

# Collator2
./target/release/pezkuwi-teyrchain --collator --bob --force-authoring \
  --tmp --port 40336 --rpc-port 9947 -- --chain pezkuwichain-local-cfde.json --port 30336

# Teyrchain Full Node 1
./target/release/pezkuwi-teyrchain --tmp --port 40337 --rpc-port 9948 -- \
  --chain pezkuwichain-local-cfde.json --port 30337
```

#### Register the teyrchain

![image](https://user-images.githubusercontent.com/2915325/99548884-1be13580-2987-11eb-9a8b-20be658d34f9.png)


## Asset Hub 🪙

This repository also contains the Asset Hub runtimes. Asset Hub is a system teyrchain providing an asset store for the
PezkuwiChain ecosystem.

### Build & Launch a Node

To run an Asset Hub node, you will need to compile the `pezkuwi-teyrchain` binary:

```bash
cargo build --release --locked --bin pezkuwi-teyrchain
```

Once the executable is built, launch the teyrchain node via:

```bash
CHAIN=asset-hub-zagros # or asset-hub-dicle
./target/release/pezkuwi-teyrchain --chain $CHAIN
```

Refer to the [setup instructions](#manual-setup) to run a local network for development.

## Bridge-hub 📝

See [the `bridge-hubs` readme](teyrchains/runtimes/bridge-hubs/README.md) for details.

## Testnets

### Paseo

[Paseo](https://pezkuwichain.io/?rpc=wss%3A%2F%2Fpaseo.rpc.amforc.com#/explorer) is the newest testnet for PezkuwiChain,
replacing pezkuwichain as a decentralised, community run, stable testnet for Teyrchain teams and dapp developers to build on.
For more information, check the [Paseo repo](https://github.com/paseo-network).

### zagros

[zagros](https://pezkuwichain.io/?rpc=wss%3A%2F%2Fzagros-rpc.polkadot.io#/explorer)
is a long running testnet for PezkuwiChain,
primarily intended to provide a testing environment for Parity to test the latest changes in the SDK.

### Testnet Teyrchains

A few testnet teyrchain instances:

- [Asset Hub zagros](https://pezkuwichain.io/?rpc=wss%3A%2F%2Fzagros-asset-hub-rpc.polkadot.io#/explorer)
- [Frequency Paseo](https://pezkuwichain.io/?rpc=wss%3A%2F%2F0.rpc.testnet.amplica.io#/explorer)

The network uses horizontal message passing (HRMP) to enable communication between teyrchains and the relay chain and,
in turn, between teyrchains. This means that every message is sent to the relay chain, and from the relay chain to its
destination teyrchain.