A private network is a configuration

Fukuii runs a permissioned network from the same binary as a public one, with the consensus algorithm chosen per deployment rather than compiled in. Who may join and who may transact are enforced against contracts you deploy and control. Both networks can run side by side in one process, isolated from each other.

docker run ghcr.io/fukuii-project/fukuii-cli

Architecture Networks

Scala 3PekkoJVMRocksDB

The seam

Choosing a consensus algorithm

Consensus sits behind one interface in Fukuii's top layer, chosen per deployment. The same property that lets a node run Proof-of-Work on one network and Proof-of-Stake on another lets it run a Proof-of-Authority network with a known validator set, from the same binary and in the same process.

Proof-of-Authority consensus algorithms hosted by the consensus module
Algorithm	Shape	Typical use
QBFT	Byzantine fault tolerant, known validator set	Consortium chains needing fast finality
Clique	Proof of Authority, signer rotation	Development and single-operator networks
Bor-style	Proof of Authority with a producer set	Sidechain and app-chain deployments

QBFT and permissioned chain configuration are specified externally. These are the normative references for what the algorithm and the genesis configuration require.

QBFT Consensus Protocol specification →Permissioned Blockchains specification →

The controls

What permissioned actually restricts

Permissioned is not one switch. Separate questions get separate answers, and a network can be strict about one while being open about another. Treating them as a single setting is the usual source of confusion about what a private network is actually protecting.

The permissioning controls and where each takes effect
Layer	What it decides	Where it is enforced
Node permissioning	Which nodes may join the network at all	At connection time, before any chain data is exchanged
Account permissioning	Which accounts may submit transactions, and what they may call	When a transaction is accepted, and again when a block carrying it is validated
Validator set	Which nodes may propose and seal blocks	Inside the consensus round, among nodes already admitted

A node admitted to the network is not thereby allowed to transact, and an account allowed to transact is not thereby allowed to produce blocks. Deciding each one deliberately is what separates a consortium chain from a public network with a firewall in front of it.

Finality

When a block stops being provisional

Proof-of-Work settles probabilistically. A block becomes harder to reverse as work accumulates on top of it, so an application decides how many confirmations it will wait for, and that number is a risk judgment rather than a fact about the chain.

A Byzantine fault tolerant algorithm settles differently. A QBFT block is final once it is committed: a supermajority of a known validator set has signed it, there is no competing chain for a node to switch to, and no reorganization can follow. One confirmation is settlement, and an application on the network needs no confirmation policy at all.

The trade is the assumption that buys it. Immediate finality requires a known validator set with enough of it reachable to agree: the algorithm tolerates fewer than a third of its validators being faulty or unreachable, and stops producing blocks beyond that, where a Proof-of-Work network with the same fraction offline keeps going and simply produces blocks more slowly. A consortium chain therefore treats validator availability as an operational requirement rather than as a background property it can assume.

Alongside, not instead

Running a private and a public network together

Each network Fukuii runs is isolated: its own state, its own metrics registry, its own configuration, supervised independently. A consortium chain and a public network can therefore run in one process without sharing storage or contending for the same dispatchers, which is one deployment to secure and audit instead of two.

The separation holds at the chain identifier as well as in storage. A transaction signed for one network carries that network's identifier and is rejected on the other, so the two cannot bleed into each other by accident. Choosing an identifier no public network already uses is part of defining a private chain, and it is what stops a signature made on a consortium chain from ever replaying somewhere real.

Configuration

Defining the network

A permissioned network is defined by its genesis file rather than by build flags: the consensus algorithm and its parameters, the initial validator set, and the addresses of the permissioning contracts deployed at genesis. Nodes read the same file, which is what makes them the same network.

Genesis

{
  "config": {
    "chainId": 1337,
    "qbft": {
      "blockperiodseconds": 5,
      "epochlength": 30000,
      "requesttimeoutseconds": 10
    },
    "nodePermissionContract": "0x0000...0001",
    "transactionPermissionContract": "0x0000...0002"
  },
  "gasLimit": "0x1fffffffffffff",
  "difficulty": "0x1",
  "extraData": "0x..."
}

Starting a node on it

fukuii \
  --genesis-file=/etc/fukuii/genesis.json \
  --data-path=/var/lib/fukuii/consortium \
  --p2p-port=30303 \
  --rpc-http-enabled \
  --rpc-http-port=8545

Permissioning is enforced by the client against contracts deployed at genesis, so changing who may connect or transact is a contract call rather than a restart. Those contracts are the network operator's to write, audit and secure, and they carry their own security-certification obligations independent of the client.

Operating it

What changes after genesis

A genesis file fixes how the network starts, not how it stays. Several things move afterward, and each moves by a different mechanism.

The validator set

The validators named in genesis are the starting set rather than a permanent one. QBFT specifies a vote: existing validators propose an addition or a removal, and the result takes effect at an epoch boundary rather than the moment it passes, so every node applies the same set at the same block. What the vote requires is in the specification linked above, because it is a property of the algorithm rather than of any client implementing it.

How nodes find each other

A public network's nodes discover peers by broadcasting. A permissioned network usually does not want to be discoverable at all, so discovery is turned off and each node is given the addresses of the others directly. Discovery and permissioning are separate controls doing different jobs: one decides who can be found, the other decides who is admitted, and a private network normally wants both.

What gas is for

A public network prices gas to ration block space among anonymous senders competing for it. A permissioned network has already decided who may transact, so there is no bidding to arbitrate, and many run with the price floor at zero. Gas then stops being a cost and goes back to being a resource limit: the block gas limit in genesis is the real control over how much work a block may carry, and a runaway contract is bounded by it rather than by what someone was willing to pay.

fukuii \
  --genesis-file=/etc/fukuii/genesis.json \
  --data-path=/var/lib/fukuii/consortium \
  --discovery-enabled=false \
  --static-nodes-file=/etc/fukuii/static-nodes.json \
  --min-gas-price=0 \
  --rpc-http-enabled