# @aztec/p2p

> This package implements the P2P networking layer for Aztec nodes using libp2p. It handles transaction propagation, block and checkpoint proposal dissemination, attestation collection for consensus, and peer management. The `P2PClient` provides the top-lev

Latest version **5.2.0** (published 2026-08-17) · 0 weekly downloads

## Install

```sh
npm install @aztec/p2p
pnpm add @aztec/p2p
yarn add @aztec/p2p
bun add @aztec/p2p
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.2.0 |
| Published | 2026-08-17 |
| First published | 2023-07-09 |
| Weekly downloads | 0 |
| TypeScript types | bundled |
| Module format | ESM |
| Node | >=20.10 |
| Dependencies | 35 |
| Unpacked size | 2.6 MB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| Maintainers | zac-williamson, leilawang, charlielye, jaosef, joss-aztecprotocol, ludamad |

## Links

- npm: https://www.npmjs.com/package/@aztec/p2p
- npm.io page: https://npm.io/package/@aztec/p2p

## Dependencies (35)

- [sha3](https://npm.io/package/sha3.md) ^2.1.4
- [tslib](https://npm.io/package/tslib.md) ^2.4.0
- [libp2p](https://npm.io/package/libp2p.md) 1.5.0
- [semver](https://npm.io/package/semver.md) ^7.6.0
- [snappy](https://npm.io/package/snappy.md) 7.2.2
- [@libp2p/tcp](https://npm.io/package/@libp2p/tcp.md) 9.0.24
- [@aztec/stdlib](https://npm.io/package/@aztec/stdlib.md) 5.2.0
- [@libp2p/mplex](https://npm.io/package/@libp2p/mplex.md) 10.0.16
- [@libp2p/crypto](https://npm.io/package/@libp2p/crypto.md) 4.0.3
- [@aztec/ethereum](https://npm.io/package/@aztec/ethereum.md) 5.2.0
- [@aztec/kv-store](https://npm.io/package/@aztec/kv-store.md) 5.2.0
- [@libp2p/peer-id](https://npm.io/package/@libp2p/peer-id.md) 4.0.7
- [interface-store](https://npm.io/package/interface-store.md) ^5.1.8
- [@aztec/constants](https://npm.io/package/@aztec/constants.md) 5.2.0
- [@aztec/simulator](https://npm.io/package/@aztec/simulator.md) 5.2.0
- [@libp2p/identify](https://npm.io/package/@libp2p/identify.md) 1.0.18
- [@aztec/foundation](https://npm.io/package/@aztec/foundation.md) 5.2.0
- [@libp2p/bootstrap](https://npm.io/package/@libp2p/bootstrap.md) 10.0.0
- [@libp2p/interface](https://npm.io/package/@libp2p/interface.md) 1.3.1
- [@aztec/epoch-cache](https://npm.io/package/@aztec/epoch-cache.md) 5.2.0
- [@libp2p/peer-store](https://npm.io/package/@libp2p/peer-store.md) 10.0.16
- [@nethermindeth/enr](https://npm.io/package/@nethermindeth/enr.md) 3.0.0-backport-306-v4
- [interface-datastore](https://npm.io/package/interface-datastore.md) ^8.2.11
- [@nethermindeth/discv5](https://npm.io/package/@nethermindeth/discv5.md) 9.0.0-backport-306-v4
- [@aztec/telemetry-client](https://npm.io/package/@aztec/telemetry-client.md) 5.2.0
- [@chainsafe/libp2p-noise](https://npm.io/package/@chainsafe/libp2p-noise.md) ^15.0.0
- [@chainsafe/libp2p-yamux](https://npm.io/package/@chainsafe/libp2p-yamux.md) ^6.0.2
- [@libp2p/peer-id-factory](https://npm.io/package/@libp2p/peer-id-factory.md) 4.1.1
- [@multiformats/multiaddr](https://npm.io/package/@multiformats/multiaddr.md) 12.1.14
- [@aztec/noir-contracts.js](https://npm.io/package/@aztec/noir-contracts.js.md) 5.2.0
- [@aztec/protocol-contracts](https://npm.io/package/@aztec/protocol-contracts.md) 5.2.0
- [@aztec/standard-contracts](https://npm.io/package/@aztec/standard-contracts.md) 5.2.0
- [@libp2p/prometheus-metrics](https://npm.io/package/@libp2p/prometheus-metrics.md) ^4.2.4
- [@chainsafe/libp2p-gossipsub](https://npm.io/package/@chainsafe/libp2p-gossipsub.md) 13.0.0
- [@aztec/noir-protocol-circuits-types](https://npm.io/package/@aztec/noir-protocol-circuits-types.md) 5.2.0

## Recent versions

- 5.2.0 (latest) — 2026-08-17
- 5.3.0-nightly.20260919 (prerelease) — 2026-09-19
- 0.0.1-dev (dev) — 2026-06-26
- 4.4.0-nightly.20260618 (nightly) — 2026-06-18
- 4.3.0-rc.1 (rc) — 2026-05-15
- 0.0.1-commit.fff30aa (commit) — 2026-04-17
- 4.0.0-devnet.4-patch.0 (devnet) — 2026-04-06
- 4.2.0-aztecnr-rc.2 (aztecnr-rc) — 2026-03-26
- 5.0.0-private.20260319 (private) — 2026-03-19
- 5.0.0-patched.20260318 (patched) — 2026-03-18
- 4.0.0-spartan.20260218 (spartan) — 2026-02-18
- 2.0.3-zkpassport (zkpassport) — 2025-12-03
- 3.0.0-manual.20251030 (manual) — 2025-10-30
- 0.0.1-fake-ceab37513c (fake-ceab37513c) — 2025-10-30
- 0.0.1-fake-c83136db25 (fake-c83136db25) — 2025-10-30
- … 1314 more at https://npm.io/package/@aztec/p2p/versions

## README

# P2P

This package implements the P2P networking layer for Aztec nodes using libp2p. It handles transaction propagation, block and checkpoint proposal dissemination, attestation collection for consensus, and peer management. The `P2PClient` provides the top-level interface used by `aztec-node`; the `BootstrapNode` class runs a lightweight discovery-only node that introduces peers to the network without participating in gossip.

## Architecture

- **P2PClient** wraps everything below. Manages lifecycle, bridges L2 block events to pool state transitions, exposes `ITxProvider` for RPC.
- **LibP2PService** is the core networking layer. Subscribes to gossipsub topics, registers req/resp handlers, runs message validation pipelines. It composes:
  - **PeerManager** — peer scoring (gossipsub + application-level), authentication (STATUS/AUTH handshakes), connection gating.
  - **DiscV5Service** — UDP-based peer discovery using Ethereum's discv5 protocol and ENR records.
  - **ReqResp** — request-response protocols: BLOCK_TXS, TX, STATUS, AUTH, PING, GOODBYE.
  - **TxCollection** — coordinates transaction fetching: fast collection for proposals/proving (deadline-driven, falls back to `BatchTxRequester`) and slow background collection for unproven blocks.
- **Mempools** sit below the service layer:
  - **TxPoolV2** — transaction mempool with explicit state machine (pending, protected, mined, soft-deleted, hard-deleted) and pluggable eviction rules.
  - **AttestationPool** — stores block/checkpoint proposals and attestations per slot. Handles equivocation detection and slash callbacks.

### Key Components

| Component | Responsibility |
|-----------|---------------|
| **P2PClient** | Top-level orchestrator. Manages lifecycle, bridges L2 block events to pool state transitions, exposes `ITxProvider` for RPC. |
| **LibP2PService** | Core networking. Subscribes to gossipsub topics, registers req/resp handlers, runs message validation pipelines. |
| **PeerManager** | Peer scoring (gossipsub + application-level), authentication (STATUS/AUTH handshakes), connection gating. |
| **DiscV5Service** | UDP-based peer discovery using Ethereum's discv5 protocol and ENR records. |
| **TxCollection** | Coordinates transaction fetching: fast collection for proposals/proving (deadline-driven, falls back to `BatchTxRequester`) and slow background collection for unproven blocks. |
| **BatchTxRequester** | Aggressive parallel fetching of missing txs from peers via BLOCK_TXS protocol. Classifies peers as pinned/dumb/smart for efficient batching. |
| **TxPoolV2** | Transaction mempool with explicit state machine (pending, protected, mined, soft-deleted, hard-deleted) and pluggable eviction rules. |
| **AttestationPool** | Stores block/checkpoint proposals and attestations per slot. Handles equivocation detection and slash callbacks. |

### Peer Lifecycle

```
Unknown → [DiscV5 discovery] → Discovered → [TCP connect] → Connected
  → [STATUS or AUTH handshake] → Authenticated → [gossip participation] → Active
```

Handshake type depends on config:
- `p2pAllowOnlyValidators` = true and peer is not protected: **AUTH** handshake (signature challenge proving validator identity). Unauthenticated peers get `appSpecificScore = -Infinity`, excluding them from all gossip.
- Otherwise: **STATUS** handshake (version compatibility check only).
- Protected peers (trusted/private/preferred): STATUS only, always considered authenticated.

Connection gating: peers with too many failed AUTH attempts (`p2pMaxFailedAuthAttemptsAllowed`, default 3) are denied inbound connections for 1 hour.

---

## Sub-module Documentation

| README | Covers |
|--------|--------|
| [Gossipsub Scoring](src/services/gossipsub/README.md) | P1-P4 parameter calculation, decay mechanics, convergence math, global thresholds, application-level penalties, tuning guidelines |
| [Transaction Validation](src/msg_validators/tx_validator/README.md) | Validator factories per entry point, individual validator descriptions with benchmarks, coverage table |
| [Proposal Validation](src/msg_validators/proposal_validator/README.md) | BlockProposal and CheckpointProposal gossipsub validation, pool admission, validator-client processing, slashing |
| [Attestation Validation](src/msg_validators/attestation_validator/README.md) | CheckpointAttestation gossipsub validation, pool admission, equivocation detection, L1 submission validation |
| [ReqResp Protocols](src/services/reqresp/README.md) | Handshake protocols (STATUS, AUTH, PING, GOODBYE), block data protocols (BLOCK_TXS, TX), rate limits, transport validation |
| [BatchTxRequester](src/services/reqresp/batch-tx-requester/README.md) | Peer classification (pinned/dumb/smart), worker architecture, BLOCK_TXS wire protocol |
| [TxPool Interface](src/mem_pools/tx_pool/README.md) | TxPool contract, storage structure, priority system, nullifier deduplication, eviction rules |
| [TxPoolV2](src/mem_pools/tx_pool_v2/README.md) | State machine, soft deletion (slot-based vs prune-based), pre-add vs post-event rules |

---

## Gossipsub Objects

All gossipsub messages pass through a shared pre-validation pipeline before topic-specific logic:

| Stage | Rule | Consequence | File |
|-------|------|-------------|------|
| 0 | Snappy decompressed size <= per-topic limit (see per-object sections) | Message dropped | `p2p/src/services/encoding.ts` |
| 1 | P2PMessage envelope deserializes | REJECT + LowToleranceError | `p2p/src/services/libp2p/libp2p_service.ts` |
| 2 | Gossipsub-level message cache dedup (configurable `seenTTL`) | Silently dropped by gossipsub | gossipsub internals |
| 3 | Application-level dedup via `MessageSeenValidator` (fixed-size circular buffer + Set) | IGNORE | `p2p/src/msg_validators/msg_seen_validator/` |

A REJECT result from any validation stage increments the gossipsub P4 (invalidMessageDeliveries) counter for the peer on that topic. P4 weight is -20, decaying over 4 slots. This is in addition to any application-level peer penalty.

### Peer Penalty Severity Reference

| Severity | Approx. strikes to ban | Used for |
|----------|------------------------|----------|
| `LowToleranceError` | ~2 | Invalid proof, deserialization failure, old double-spend |
| `MidToleranceError` | ~10 | Most validation failures (metadata, data, gas, phases, size) |
| `HighToleranceError` | ~50 | Timestamp expiry, block header, recent double-spend, rate limits |

See [Gossipsub Scoring](src/services/gossipsub/README.md) for full score calculation, decay mechanics, and threshold alignment.

### Object Summary

| Topic | Snappy Limit | Description | Detailed Docs |
|-------|-------------|-------------|---------------|
| `tx` | 512 KB | Transactions. Two-stage validation: fast validators (parallel) then proof verification. Pool pre-check between stages avoids wasting CPU on proof for txs the pool would reject. | [Tx Validation](src/msg_validators/tx_validator/README.md) |
| `block_proposal` | 10 MB | Block proposals from proposers. Validated for slot timing, signature, proposer identity, tx hash integrity. Validator nodes may re-execute and slash on state mismatch. | [Proposal Validation](src/msg_validators/proposal_validator/README.md) |
| `checkpoint_proposal` | 10 MB | Checkpoint proposals containing the final block. Same proposal validation as blocks, plus embedded block extraction and separate validation. | [Proposal Validation](src/msg_validators/proposal_validator/README.md) |
| `checkpoint_attestation` | 5 KB | Validator attestations for checkpoints. Validated for slot timing, attester/proposer signatures, committee membership. Equivocation at count=2 triggers slash callback. | [Attestation Validation](src/msg_validators/attestation_validator/README.md) |

---

## ReqResp Protocols

See [ReqResp Protocols](src/services/reqresp/README.md) for full protocol details.

### Rate Limits (Responder Side)

| Protocol | Peer Limit | Global Limit |
|----------|-----------|-------------|
| PING | 5/s | 10/s |
| STATUS | 5/s | 10/s |
| AUTH | 5/s | 10/s |
| GOODBYE | 5/s | 10/s |
| BLOCK_TXS | 10/s | 200/s |
| TX | 10/s | 200/s |

Per-peer limit exceeded: `HighToleranceError` + `RATE_LIMIT_EXCEEDED` status. Global limit exceeded: `RATE_LIMIT_EXCEEDED` status only (no peer penalty).

### Peer Score Thresholds

| Score | State | Action |
|-------|-------|--------|
| > -50 | Healthy | Normal |
| -100 < score <= -50 | Disconnect | GOODBYE sent + disconnect on next heartbeat |
| <= -100 | Banned | GOODBYE sent + disconnect on next heartbeat; banned for `P2P_PEER_BAN_DURATION_SECONDS` (default 24h) |

Once a peer is banned its score is pinned at the ban level for the configured duration (it does not decay-recover),
and only lifts when the window expires. See [Gossipsub Scoring](src/services/gossipsub/README.md#ban-duration) for details.

### Protocol Summary

| Protocol | Request | Response | Purpose |
|----------|---------|----------|---------|
| STATUS | Own blockchain state | Peer's blockchain state | Version compatibility check on connect |
| AUTH | Random challenge (`Fr`) | Signed challenge response | Validator identity verification on connect |
| PING | (empty) | `pong` | Liveness check |
| GOODBYE | Reason byte | (none meaningful) | Graceful disconnect |
| BLOCK_TXS | Archive root + tx hashes + BitVector | Txs + BitVector of availability | Batch tx fetching for proposals/proving |
| TX | `TxHashArray` | Matching txs | Individual tx fetching |

Request payloads are NOT snappy-compressed (asymmetric: only responses use snappy).

---
_Source: https://npm.io/package/@aztec/p2p · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._