pezkuwichain
59ac32e3b2
- Replace 68 "[here]" links with descriptive text (MD059) - Fix table separator spacing in 6 project files (MD060) - Add trailing newlines to 2 files (MD047) - Disable MD060 rule for .claude/ internal files - Update markdownlint config with MD060: false All project files now pass markdownlint --config .github/.markdownlint.yaml 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
215 lines
8.7 KiB
Markdown
215 lines
8.7 KiB
Markdown
# Pezcumulus ☁️
|
|
|
|
[](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
|
|
|
|
|
|
|
|
|
|
## 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-kusama
|
|
./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.
|