Protocol & Developer Documentation

The documentation is divided into sections covering the base protocol (Layer-1), the mining system (Layer-2 HexGrid), RPC interfaces, economic model, upcoming privacy features, and long-term architectural plans.

1. High-Level Overview

xPrivFi is a clean-slate Layer-1 blockchain for digital cash with:

• permanent fixed supply: 1,000,000 XPF
• RandomHash / iPoW proof-of-work with ~6-minute blocks
• an account-based state model (balances + nonces)
• HexGrid mining (Layer-2) with 200–890 participants per round
• future optional privacy via CP-Shield (commitments + nullifiers)
• simple JSON-RPC interface for wallets, apps, and explorers

2. Monetary Model

The supply of XPF is permanently capped at 1,000,000. The economic design is intentionally minimal:

• 500,000 XPF — genesis (creator reserve + Dex_Main ecosystem wallet)
• 500,000 XPF — mined across ~5.7 years
• 1 XPF emission per round (6-minute target)
• 30-second cooldown between rounds
• no inflation, no governance minting, no staking

Layer-2 participation fees (e.g. 0.001 XPF) activate only after XPF is listed on an external marketplace. These fees are routed to Dex_Main — a closed-loop ecosystem wallet.

3. Layer-1 Protocol (Consensus)

The xPrivFi L1 protocol maintains a simple, auditable consensus surface.

3.1 Block Header

• height
• prevHash
• timestamp
• difficulty
• nonce (PoW)
• miner address

3.2 Consensus Rules

for each new block B:
  1. verify PrevHash matches tip
  2. check timestamp is valid (not far future)
  3. verify median-past-time
  4. compute expectedDiff using CP-Diff v1.0
  5. PoW(RandomHash(header)) <= target(difficulty)
  6. apply all transactions
  7. reward = MiningRewardAtoms(B.height)
  8. ensure reward <= remainingMineable
  9. credit miner with reward + fees

3.3 State Model

• balances
• nonces (replay protection)
• remaining mineable supply
• total mined amount

4. Transactions

XPF uses an account-based transaction format:

• from, to
• amount, fee
• nonce
• public key
• signature

Fees are credited to miners. Once block rewards end, fees become the sole source of miner compensation.

5. HexGrid Mining (Layer-2)

Mining in xPrivFi is performed via the HexGrid Layer-2 game. It is fully off-chain and does not modify consensus rules.

5.1 Round Structure

• round length: 6 minutes
• cooldown: 30 seconds
• participants: 200–890 required
• every participant has equal probability to win

5.2 Reward Flow

1. players join a round (optionally: fee after listing)
2. players select HexGrid tiles
3. off-chain engine selects 1 winner
4. engine submits a normal on-chain reward transaction
5. winner receives 1 XPF instantly in wallet

5.3 Fees

• free until first exchange listing
• after listing: tiny fee (example: 0.001 XPF)
• fee is routed to Dex_Main

6. JSON-RPC Interface

The RPC API allows wallets, explorers and miners to interact with the node.

6.1 Standard Methods

• get_balance(address)
• get_nonce(address)
• submit_tx(tx)
• get_sync_status()
• get_difficulty_history()

6.2 Mining-Related (if exposed)

• getCurrentRound()
• getRoundState()
• getWinnerHistory()

These endpoints vary depending on your mining pool implementation.

7. Privacy Roadmap (CP-Shield)

Privacy is introduced through optional higher-layer features without altering the fundamental L1 consensus rules.

• encrypted commitment tree
• nullifier set (unlinkable spent notes)
• transparent ↔ shielded conversion
• optional ZK proofs (Groth16 / Plonk)

Privacy is always opt-in.

8. Future Work

• mobile wallets (Android / iOS)
• light wallets + seedless UX
• multi-client implementations (Go v2, Rust, C++)
• improved explorer backend
• testnet release
• optional compatibility with RootBaseLayer (external project)