Getting Started - zoobc/zoobc-core GitHub Wiki

Running A Node

The core node can be run by anyone that want to join the network, to run the core-node application the machine will need the following files configured:

core/
  zoobc [binary file]
  resource/
    config.toml
    node_keys.json

Configurations:

  • resource/config.toml Configuration for the running node, the full description of the config file can be seen here

  • resource/node_keys.json Key pair for the smithing node. (see smithing: here)

Node Created Files:

  • resource/zoobc.db (default)

    On running the node, will be created containing the genesis block of mainchain and the spinechain.

  • resource/snapshots/ (default)

    This directory will be created if we are to join already long-running network to store the snapshot files.

Internal (wip: need better naming)

The core node application consists of two main components, the services and the jobs.

  • Services

    The core services are API that are open to the user, they are consists of:

    • Client API

      These are grpc endpoints that can be consumed by both wallet, explorer, or other client that want to post or get data to/from core node.

      Note: to accomodate the browser-based client, we open a separate proxy service using grpcwebproxy. ref:

    • Node API

      These are grpc endpoints that are opened to other running node as a gateway to broadcast / receive data. ref:

    In total the core node opened 3 client consumeable ports, the grpc-client-api, proxy-client-api and the node-api.

  • Jobs

    Jobs are periodically running operations in the core node.

    • Block Creation [ Smithing ]

      The periodic operation ran to check if current node is elligible to generate block yet.

      • Mainchain
        run-period = 500 ms
content = Transaction, Receipt

        The main chain of the core node, block on this chain store transactions posted by users and receipt to accomodate Proof Of Participation

        • Transactions

          Transactions are action that can be taken on the zoobc core node. They are separated into different kind of actions by Transaction Type. ref: Transaction Type

        • Receipts

          Receipts are special object that can proof two nodes have communicated with each other (in form of block broadcast or transaction broadcast). ref: Receipt

        When node is selected to generate block, it does the following things:

        • Fetch Transaction From Mempool

          Node will select few transactions that it wants to include to the next block if exists from the Mempool, or generate Empty Block otherwise.

        • Fetch Receipt From NodeReceipt

          Node will select sets of node receipts to be published to the network. The published receipt will later help the node to gain more Participation Score.

      • Spinechain
        run-period = 500 ms
content = SpinePublicKeys

        A second chain run by zoobc core node. This chain act as a checkpoint for the mainchain, containing SpinePublicKeys

        • Spine Public Keys

          List of public keys from the node registry at spine block height. (todo: need @iltoga fill this)

      After blocks are persisted to the chain, it'll be broadcasted to its peer via Peer to Peer layer.

      ref:

    • Blockchain Synchronization

      Blockchain synchronization process consists of several operations:

      • Initial Block Synchronization

        It's a job that's run when the node initially started. It tries to synchronize the blockchain state of the network with it's peers so that the node can start smithing for blocks. More Info

      • Blockchain Download

        It's a cron job that is performed every a sometime defined in the constant GetMoreBlocksDelay. It will request the state of blockchain of the node's peers and compare it with the node's blockchain state. If the node finds its state is lower it will apply the peer's blockchain state into his blockchain. More Info

      • Process Fork

        This process is a companion process to the Blockchain Download process. If the blocks downloaded conflicts with the current node's blockchain state, this process will try to resolve the blockchain state the node should have. More Info

    • Data Prune

      descrition