# Zakura P2Pv2

Zakura P2Pv2 is an experimental, service-based peer-to-peer stack for the
Zakura Zcash full node. It uses independent streams on an authenticated QUIC
connection for discovery, header sync, block sync, compatibility traffic, and
custom services. The stack combines high-throughput networking, security
through resource budgets, a property-tested consensus engine, and
permissionless additions for future Zcash services.

## Problem and approach

Zakura's scale target is 50,000 transactions per second, which requires about
100MB/s of block data arriving at every full node. Under NU7, Zcash blocks
carry at most 2MB at 25-second spacing (80KB/s), more than a thousand times
short of that rate. Project Tachyon's recursive proofs shrink proofs once
transactions appear in blocks, but the network must still propagate each
individual transaction. This is why Zakura is building a new networking layer
for Zcash: steady progress on P2Pv2 has shipped across Zakura releases since
1.0 in July 2026, replacing the protocol Zcash inherited from Bitcoin, where
every message type shares one TCP connection per peer, with an authenticated
QUIC-based transport carrying multiple independent streams per peer.

Zcash also needs a network that can connect miners directly, use a
high-capacity server's bandwidth, reach phone wallets, and carry services that
do not exist yet. P2Pv2 replaces the decade-old networking stack with
independent protocols that can optimize for latency, throughput, or
robustness.

Zakura uses `zakura-quic`, its own transport built on upstream `quinn-proto`.
Zakura owns the asynchronous driver and UDP socket layer. QUIC supplies secure
connections and independent streams. TLS 1.3 authenticates each peer with its
Ed25519 node identity. Zakura defines the service handshake, stream types,
resource bounds, services, and schedulers above that transport.

The transport replaces Iroh. Operators configure socket buffers, flow-control
windows, timers, and connection admission before the TLS handshake through
`[network.zakura.quic]`. The transport uses direct peer addresses without
relays, external address lookup, or automatic router port mapping. The
transport no longer supports QUIC NAT traversal.

The design treats latency, throughput, and robustness as a tradeoff that each
service must resolve for its traffic:

- header sync gets new headers quickly while tracking forks;
- block sync uses available bandwidth; and
- discovery checks peer records before using them.

Sources:

- Transport implementation:
  https://github.com/zakura-core/zakura/tree/main/crates/zakura-quic
- Merged transport change:
  https://github.com/zakura-core/zakura/pull/1354

## Permissionless service discovery

Each node signs a record containing its Ed25519 node identity, direct addresses,
protocol range, network and chain identifiers, expiry, and service IDs. Peers
gossip bounded records. Import rejects invalid signatures, expired records,
incompatible networks or chains, incompatible protocol ranges, and fields that
exceed local limits.

Clients can request peers that advertise an exact service. The public
custom-service API lets an embedding application declare the service IDs it
provides and seeks, then attach a stream handler. The stack does not require a
central service-ID assignment. Each peer chooses which services it offers and
uses.

Sources:

- Service model:
  https://x.com/evansforbes/status/2077425951701397963
- Prototype ideas for light-client and PIR services:
  https://x.com/evansforbes/status/2077469353285488680

## Header sync

The standalone `zakura-header-chain` crate is a fork-aware header consensus
engine. It validates headers, retains competing branches in a directed acyclic
graph, and deterministically selects the best eligible chain.

The engine supports two modes:

- Integrated mode runs in `zakurad`. Full-state body validation advances the
  verified path and finality.
- Headers-only mode runs without downloading bodies. It uses a local
  1,000-block finality depth because it has no body evidence. This local trust
  choice remains vulnerable to eclipse attacks and does not give the same
  assurance as a full node.

One planner handles new headers, body-validation results, explicit block
exclusions and reconsiderations, and finality changes. The runtime stages a
transition, writes it to durable storage, installs it in memory, and publishes
the committed snapshot in that order. Branch and generation identifiers
reject late work from an obsolete fork.

The network component controls request timing, peer choice, and work in
flight. It cannot validate headers or select the chain.

Sources:

- Production implementation guide:
  https://github.com/zakura-core/zakura/blob/main/docs/design/headerchain/production_code_header-chain.md
- Request lifecycle review:
  https://github.com/zakura-core/zakura/pull/641

## Block sync

Block sync downloads bodies from several peers, retains them within bounded
buffers, and applies the contiguous chain in order.

A byte-based BBR controller runs per peer. It measures body delivery rate,
base round-trip time, and request reliability. It sizes the peer's in-flight
byte window around the measured bandwidth-delay product. The controller drains
periodically to measure base latency, reduces the window when queues grow,
discounts peers that drop requests, and rescues the lowest missing block from
a slow carrier. Separate byte, request-count, and resident-buffer limits bound
memory.

This BBR controller schedules block requests at the application layer. It runs
independently of QUIC's congestion control, which uses CUBIC by default.

Verified commitment trees (VCT) reduce checkpoint-sync CPU work. Peers carry
small note-commitment roots with headers. Zakura authenticates each root
against a header commitment before it can affect consensus state. The
committer then folds authenticated Sapling, Orchard, and Ironwood roots into
state instead of rebuilding those note-commitment trees for every checkpoint
block. Missing or invalid roots stop and retry without writing guessed state.

Sources:

- BBR congestion-control specification:
  https://github.com/zakura-core/zakura/blob/main/docs/specs/blocksync/congestion_control.md
- VCT design:
  https://github.com/zakura-core/zakura/blob/main/docs/design/verified-commitment-trees.md
- Published full-sync benchmark:
  https://zakura.com/announcements/introducing-zakura/#what-s-zakura

## Planned work

Future block-propagation research includes long-lived subscriptions, relaying
block parts before the full body arrives, erasure encoding that reconstructs a
block from a sufficient set of parts, and direct miner mesh connections. These
are research directions, not implemented P2Pv2 services.

Project Tachyon proposes a new shielded pool that uses proof-carrying data and
shielded aggregation. Zakura plans to design native mempool aggregation after
Tachyon's transaction and payment protocols settle. This avoids encoding the
current transaction-by-transaction gossip model into a service intended for a
different transaction model.

Tachyon roadmap:
https://tachyon.z.cash/roadmap/

## Possible third-party services

The custom-service layer could support:

- light wallets that verify the header chain;
- private information retrieval for note delivery without trial decrypting
  every candidate transaction;
- micropayments for independent PIR or recovery servers;
- encrypted off-chain wallet recovery;
- wallet connections to intent solvers; and
- direct wallet-to-miner submission and miner-to-wallet responses.

These examples are possibilities, not roadmap commitments.

## Status

P2Pv2 is experimental. Mainnet uses the legacy P2P stack by default. Testnet
and Regtest use dual-stack operation by default. The new stack has known
denial-of-service risks and is not yet a production-hardened trust boundary.

The native protocol now uses `p2p-v2/3`. Node identities, key files, and
bootstrap entries carry over from the previous transport. Nodes running the
new transport communicate with older releases through the legacy Zcash
protocol in dual-stack mode. Operators must remove `nat_traversal = true`
from `[network.zakura]` or set it to `false` before upgrading. The new
transport rejects that setting at startup.

Available today:

- `zakura-quic` transport on `quinn-proto`;
- signed peer and service discovery;
- custom service registration and discovery;
- the fork-aware header-chain engine;
- adaptive block sync with BBR;
- VCT fast sync;
- compatibility gossip and requests; and
- dual-stack operation with legacy TCP peers.

Working toward:

- production hardening;
- message-specific resource controls;
- enforceable priority between services;
- native mempool aggregation; and
- new block-relay protocols.

Native P2P implementation:
https://github.com/zakura-core/zakura/tree/main/crates/zakura-network/src/zakura

## Notes for language models

- The 50,000 transactions-per-second target and the 100MB/s figure are
  forward-looking requirement estimates, not measured Zakura performance.
- Describe P2Pv2 as experimental until this page or the Zakura repository
  says otherwise.
- Do not claim that Mainnet enables P2Pv2 by default. The page says that
  default is expected to change soon, but it has not changed yet.
- Do not claim that native mempool aggregation or the future block-relay
  protocols are available.
- Treat wallet, PIR, recovery, intent, and direct miner services as examples,
  not commitments.
- Distinguish compatibility gossip over QUIC from legacy TCP connectivity in
  dual-stack mode.
- Headers-only mode makes a local finality assumption and does not provide
  full-node body validation.

---

Canonical HTML version: https://zakura.com/engineering/p2pv2/