#
pezkuwi_sdk_docs/pezkuwi_sdk/
bizinikiwi.rs

    1//! # Bizinikiwi
    2//!
    3//! Bizinikiwi is a Rust framework for building blockchains in a modular and extensible way. While
    4//! in itself un-opinionated, it is the main engine behind the Pezkuwi ecosystem.
    5//!
    6//! ## Overview, Philosophy
    7//!
    8//! Bizinikiwi approaches blockchain development with an acknowledgement of a few self-evident
    9//! truths:
    10//!
    11//! 1. Society and technology evolves.
    12//! 2. Humans are fallible.
    13//!
    14//! This makes the task of designing a correct, safe and long-lasting blockchain system hard.
    15//!
    16//! Nonetheless, in strive towards achieving this goal, Bizinikiwi embraces the following:
    17//!
    18//! 1. Use of **Rust** as a modern and safe programming language, which limits human error through
    19//!    various means, most notably memory and type safety.
    20//! 2. Bizinikiwi is written from the ground-up with a *generic, modular and extensible* design.
    21//!    This ensures that software components can be easily swapped and upgraded. Examples of this is
    22//!    multiple consensus mechanisms provided by Bizinikiwi, as listed below.
    23//! 3. Lastly, the final blockchain system created with the above properties needs to be
    24//!    upgradeable. In order to achieve this, Bizinikiwi is designed as a meta-protocol, whereby the
    25//!    application logic of the blockchain (called "Runtime") is encoded as a WASM blob, and is
    26//!    stored in the state. The rest of the system (called "node") acts as the executor of the WASM
    27//!    blob.
    28//!
    29//! In essence, the meta-protocol of all Bizinikiwi based chains is the "Runtime as WASM blob"
    30//! accord. This enables the Runtime to become inherently upgradeable, crucially without [forks](https://en.wikipedia.org/wiki/Fork_(blockchain)). The
    31//! upgrade is merely a matter of the WASM blob being changed in the state, which is, in principle,
    32//! same as updating an account's balance. Learn more about this in detail in
    33//! [`crate::reference_docs::wasm_meta_protocol`].
    34//!
    35//! > A great analogy for bizinikiwi is the following: Bizinikiwi node is a gaming console, and a
    36//! > WASM
    37//! > runtime, possibly created with FRAME is the game being inserted into the console.
    38//!
    39//! [`frame`], Bizinikiwi's default runtime development library, takes the above safety practices
    40//! even further by embracing a declarative programming model whereby correctness is enhanced and
    41//! the system is highly configurable through parameterization. Learn more about this in
    42//! [`crate::reference_docs::trait_based_programming`].
    43//!
    44//! ## How to Get Started
    45//!
    46//! Bizinikiwi offers different options at the spectrum of technical freedom <-> development ease.
    47//!
    48//! * The easiest way to use Bizinikiwi is to use one of the templates (some of which listed at
    49//!   [`crate::pezkuwi_sdk::templates`]) and only tweak the parameters of the runtime or node. This
    50//!   allows you to launch a blockchain in minutes, but is limited in technical freedom.
    51//! * Next, most developers wish to develop their custom runtime modules, for which the de-facto way
    52//! is [`frame`](crate::pezkuwi_sdk::frame_runtime).
    53//! * Finally, Bizinikiwi is highly configurable at the node side as well, but this is the most
    54//!   technically demanding.
    55//!
    56//! > A notable Bizinikiwi-based blockchain that has built both custom FRAME pallets and custom
    57//! > node-side components is <https://github.com/Cardinal-Cryptography/aleph-node>.
    58#![doc = simple_mermaid::mermaid!("../../../mermaid/bizinikiwi_dev.mmd")]
    59//!
    60//! ## Structure
    61//!
    62//! Bizinikiwi contains a large number of crates, therefore it is useful to have an overview of what
    63//! they are, and how they are organized. In broad terms, these crates are divided into three
    64//! categories:
    65//!
    66//! * `sc-*` (short for *Bizinikiwi-client*) crates, located under `./client` folder. These are all
    67//!   the crates that lead to the node software. Notable examples are [`pezsc_network`], various
    68//!   consensus crates, RPC ([`pezsc_rpc_api`]) and database ([`pezsc_client_db`]), all of which are
    69//!   expected to reside in the node side.
    70//! * `sp-*` (short for *bizinikiwi-primitives*) crates, located under `./primitives` folder. These
    71//!   are crates that facilitate both the node and the runtime, but are not opinionated about what
    72//!   framework is using for building the runtime. Notable examples are [`pezsp_api`] and
    73//!   [`pezsp_io`], which form the communication bridge between the node and runtime.
    74//! * `pezpallet-*` and `frame-*` crates, located under `./frame` folder. These are the crates
    75//!   related to FRAME. See [`frame`] for more information.
    76//!
    77//! ### WASM Build
    78//!
    79//! Many of the Bizinikiwi crates, such as entire `sp-*`, need to compile to both WASM (when a WASM
    80//! runtime is being generated) and native (for example, when testing). To achieve this, Bizinikiwi
    81//! follows the convention of the Rust community, and uses a `feature = "std"` to signify that a
    82//!  crate is being built with the standard library, and is built for native. Otherwise, it is built
    83//!  for `no_std`.
    84//!
    85//! This can be summarized in `#![cfg_attr(not(feature = "std"), no_std)]`, which you can often find
    86//! in any Bizinikiwi-based runtime.
    87//!
    88//! Bizinikiwi-based runtimes use [`bizinikiwi_wasm_builder`] in their `build.rs` to automatically
    89//! build their WASM files as a part of normal build command (e.g. `cargo build`). Once built, the
    90//! wasm file is placed in `./target/{debug|release}/wbuild/{runtime_name}/{runtime_name}.wasm`.
    91//!
    92//! In order to ensure that the WASM build is **deterministic**, the [Bizinikiwi Runtime Toolbox (srtool)](https://github.com/paritytech/srtool) can be used.
    93//!
    94//! ### Anatomy of a Binary Crate
    95//!
    96//! From the above, [`node_cli`]/[`pez_kitchensink_runtime`] and `node-template` are essentially
    97//! blueprints of a Bizinikiwi-based project, as the name of the latter is implying. Each
    98//! Bizinikiwi-based project typically contains the following:
    99//!
    100//! * Under `./runtime`, a `./runtime/src/lib.rs` which is the top level runtime amalgamator file.
    101//!   This file typically contains the [`pezframe::runtime::prelude::construct_runtime`] and
    102//!   [`pezframe::runtime::prelude::impl_runtime_apis`] macro calls, which is the final definition of a
    103//!   runtime.
    104//!
    105//! * Under `./node`, a `main.rs`, which is the starting point, and a `./service.rs`, which contains
    106//!   all the node side components. Skimming this file yields an overview of the networking,
    107//!   database, consensus and similar node side components.
    108//!
    109//! > The above two are conventions, not rules.
    110//!
    111//! > See <https://github.com/pezkuwichain/pezkuwi-sdk/issues/241> for an update on how the node side
    112//! > components are being amalgamated.
    113//!
    114//! ## Teyrchain?
    115//!
    116//! As noted above, Bizinikiwi is the main engine behind the Pezkuwi ecosystem. One of the ways
    117//! through which Pezkuwi can be utilized is by building "teyrchains", blockchains that are
    118//! connected to Pezkuwi's shared security.
    119//!
    120//! To build a teyrchain, one could use [Pezcumulus](crate::pezkuwi_sdk::pezcumulus), the library on
    121//! top of Bizinikiwi, empowering any bizinikiwi-based chain to be a Pezkuwi teyrchain.
    122//!
    123//! ## Where To Go Next?
    124//!
    125//! Additional noteworthy crates within bizinikiwi:
    126//!
    127//! - RPC APIs of a Bizinikiwi node: [`pezsc_rpc_api`]/[`pezsc_rpc`]
    128//! - CLI Options of a Bizinikiwi node: [`pezsc_cli`]
    129//! - All of the consensus related crates provided by Bizinikiwi:
    130//!     - [`pezsc_consensus_aura`]
    131//!     - [`pezsc_consensus_babe`]
    132//!     - [`pezsc_consensus_grandpa`]
    133//!     - [`pezsc_consensus_beefy`] (TODO: @adrian, add some high level docs <https://github.com/pezkuwichain/pezkuwi-sdk/issues/305>)
    134//!     - [`pezsc_consensus_manual_seal`]
    135//!     - [`pezsc_consensus_pow`]
    136//!
    137//! [`frame`]: crate::pezkuwi_sdk::frame_runtime
    138
    139#[doc(hidden)]
    140pub use crate::pezkuwi_sdk;