pezkuwi-sdk/pezcumulus

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.

Pezcumulus SDK

A set of tools for writing Bizinikiwi-based PezkuwiChain teyrchains. Refer to the included overview for architectural details, and the Connect to a relay chain how-to guide 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 is a consensus engine for Bizinikiwi that follows a PezkuwiChain relay chain. This will run a PezkuwiChain node internally, and dictate to the client and synchronization algorithms which chain to follow, finalize, and treat as best.

Collator

A PezkuwiChain 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.

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

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

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.

To launch a local network, you can use zombienet for quick setup and experimentation or follow the manual setup.

Zombienet

We use Zombienet to spin up networks for integration tests and local networks. Follow these installation steps 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.

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:

# 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

# 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

# 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

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:

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

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

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

Refer to the setup instructions to run a local network for development.

Bridge-hub 📝

See the bridge-hubs readme for details.

Testnets

Paseo

Paseo 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.

zagros

zagros 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
• Frequency Paseo

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.