Zcash P2P Network Protocol

Preamble

ZIP

204

Title

Zcash P2P Network Protocol

Owners

• Daira-Emma Hopwood
• Kris Nuttycombe

Status

Draft

Category

Network

Created

2026-02-05

License

MIT

Discussions-To

https://github.com/zcash/zips/issues/352

Terminology

The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "RECOMMENDED" in this document are to be interpreted as described in BCP 14¹ when, and only when, they appear in all capitals.

The terms "Mainnet" and "Testnet" are to be interpreted as described in section 3.12 of the Zcash Protocol Specification.²

The term "network upgrade" is to be interpreted as described in ZIP 200.³

The term "block chain" in this document is to be interpreted as described in section 3.3 of the Zcash Protocol Specification.⁴

peer

A network node that participates in the Zcash P2P protocol by maintaining one or more TCP connections to other peers and exchanging protocol messages.

connection

A TCP session between two peers over which P2P messages are exchanged.

inbound connection

A connection that was initiated by the remote peer.

outbound connection

A connection that was initiated by the local node.

protocol version

A 32-bit integer identifying the set of protocol features supported by a node. Higher values indicate support for more recent features.

Abstract

This ZIP specifies the Zcash peer-to-peer network protocol, including connection setup, message framing, message types, and relay behavior. It is intended to be sufficient for an implementor to build a conformant Zcash network peer.

Motivation

There is currently no single document that specifies the full Zcash P2P network protocol. While Bitcoin protocol documentation exists, the Zcash protocol has diverged in several significant ways: network magic bytes differ, protocol version numbers follow an independent numbering scheme, inventory types include MSG_WTX⁵, and network upgrade activation drives protocol versioning and peer management ⁶⁷.

This ZIP consolidates the protocol specification into a single normative reference, enabling independent implementations and protocol analysis.

This ZIP does not specify the encoding of transactions and blocks; for those, refer to the Zcash Protocol Specification⁸⁹.

Specification

Network Parameters

Magic Bytes

Each Zcash network is identified by a 4-byte magic value that appears at the start of every protocol message. A node MUST reject messages whose magic bytes do not match the expected network.

Default Ports

DNS Seeds

The following DNS seed hostnames are used for initial peer discovery.

Mainnet:

• dnsseed.z.cash
• dnsseed.str4d.xyz
• mainnet.seeder.zfnd.org
• mainnet.is.yolo.money

Testnet:

• dnsseed.testnet.z.cash
• testnet.seeder.zfnd.org
• testnet.is.yolo.money

Regtest does not use DNS seeds or hardcoded seed nodes.

Peer Discovery

A node discovers peers through the following mechanisms:

1. DNS seeding. On startup, a node queries the DNS seed hostnames listed above for A and AAAA records. The zcashd implementation does this only if the address manager is empty or if fewer than 2 outbound connections have been established within 11 seconds; the Zebra implementation always performs DNS lookups on startup (alongside consulting a persistent address cache).
2. Hardcoded seed nodes. If DNS seeding fails or is insufficient, the node MAY fall back to a compiled-in list of seed node addresses. In the zcashd implementation these hardcoded addresses may be found in the chain parameters for the relevant network. DNS seeding is preferred over hardcoded seed nodes.
3. Address relay. Connected peers exchange address information using addr and getaddr messages (see addr and getaddr). This mechanism operates independently of the above.

Connection Handling

Transport

All connections use unencrypted TCP. The protocol does not provide transport-layer encryption or authentication.

Connection Limits

The specific connection limits are implementation-defined. The zcashd implementation defaults to a maximum of 125 peer connections (DEFAULT_MAX_PEER_CONNECTIONS), of which a maximum of 8 are outbound connections (MAX_OUTBOUND_CONNECTIONS). The Zebra implementation computes its limits from a configurable initial target size (default 25), applying multipliers to derive an outbound limit of 75 and an inbound limit of 125.

Timeouts

A node SHOULD disconnect a peer if no message has been received from that peer within a reasonable timeout period. The zcashd implementation uses 1200 seconds (20 minutes, TIMEOUT_INTERVAL) for this purpose; the Zebra implementation uses a 20-second request timeout (REQUEST_TIMEOUT). Automatic ping messages (see ping) are sent periodically to keep connections alive and measure latency.

Additional timeout rules:

• A node SHOULD close the connection if a peer has not sent a version message within a reasonable time after connection establishment. The zcashd implementation uses 60 seconds; the Zebra implementation uses 3 seconds (HANDSHAKE_TIMEOUT).
• A node SHOULD close the connection if a peer has not responded to a ping with a corresponding pong within a reasonable time. The zcashd implementation uses 1200 seconds (20 minutes); the Zebra implementation uses 20 seconds (REQUEST_TIMEOUT).

The specific timeout values are implementation-defined.

Message Framing

Every protocol message consists of a 24-byte header followed by a variable-length payload.

Message Header

The total header size is 24 bytes.

Command String Validation

The command field MUST contain only printable ASCII characters (bytes in the range 0x20 to 0x7E inclusive) up to the first NUL byte (0x00). After the first NUL byte, all remaining bytes MUST be 0x00. A message that violates these constraints MUST be ignored.

The following command strings are currently used on the Zcash network:

version, verack, ping, pong, reject, addr, addrv2, getaddr, inv, getdata, notfound, getblocks, getheaders, headers, block, tx, mempool, filterload, filteradd, filterclear, alert.

Maximum Message Size

The maximum payload size is 2,097,152 bytes (2 MiB). A node MUST reject any message whose length field exceeds this limit.

Checksum Verification

The checksum field contains the first 4 bytes of the double-SHA-256 hash of the payload:

checksum = SHA-256(SHA-256(payload))[0..4]

A node MUST verify the checksum after receiving the full payload and MUST reject the message if the checksum does not match.

Data Types and Encoding

All multi-byte integer types are encoded in little-endian byte order unless otherwise specified. The integer types used in this specification (uint8, uint16, int32, uint32, int64, uint64) have their conventional meanings.

CompactSize

A variable-length unsigned integer encoding used for lengths and counts:

Encodings MUST be canonical: the shortest possible encoding MUST be used for any given value. A node MUST reject messages containing non-canonical CompactSize encodings.

Strings

Character strings are encoded as a CompactSize length prefix followed by that many bytes of string data. There is no NUL terminator.

Network Address (CService)

A network address without associated metadata, as inherited from the Bitcoin protocol:

IPv4 addresses are represented as IPv4-mapped IPv6 addresses as defined in RFC 4291 section 2.5.5.2¹¹: the first 12 bytes are 00 00 00 00 00 00 00 00 00 00 FF FF followed by the 4-byte IPv4 address.

Peer Address (CAddress)

A network address with associated metadata, used in version, addr, and other messages:

When the negotiated protocol version (see Protocol Version Negotiation) is ≥ 31402 (CADDR_TIME_VERSION) and the address appears in a context other than a version message, the encoding is preceded by a uint32 timestamp field:

Service Flags

Service flags are advertised in the services field of version messages and CAddress structures. In the table below, bit $k$ refers to the bit with numeric weight $2^k$; that is, the services field has the corresponding flag set if and only if services & (1 << k) != 0.

Bits 24–31 are reserved for temporary experiments.

Inventory Vectors

Inventory vectors identify objects (transactions and blocks) for relay. The format depends on the type:

Because MSG_TX and MSG_WTX entries have different sizes (36 and 68 bytes respectively), they may be mixed in a single inv or getdata message. The total message size is therefore not determined solely by the entry count and MUST be determined by parsing each entry individually.

A node MUST reject inventory vectors with unrecognized type codes. A node MUST reject MSG_WTX inventory vectors if the negotiated protocol version is less than 170014.

Connection Handshake

Peers perform a version handshake immediately upon establishing a TCP connection.

Handshake Sequence

1. The initiating (outbound) peer sends a version message.
2. The receiving (inbound) peer sends its own version message.
3. Each peer, upon receiving a valid version message, responds with a verack message.
4. The negotiated protocol version is min(local_version, remote_version).

A peer MUST NOT send any message other than version before receiving the remote peer's version message. A peer MUST NOT send any message other than verack after sending its version and before receiving the remote peer's verack.

If validation of the version message received from a peer fails, the node MUST disconnect the peer. See (see Version Validation) below for additional details.

Protocol Version Negotiation

Each peer advertises its own protocol version in its version message. The negotiated protocol version for the connection is defined as:

negotiated_version = min(local_version, remote_version)

Before the handshake completes, messages are serialized using the initial protocol version 209 (INIT_PROTO_VERSION). Once both version and verack messages have been exchanged, the negotiated protocol version is used for all subsequent interpretation of protocol features and message semantics on that connection. In particular, the negotiated protocol version determines:

• Whether CAddress structures include a time field (version ≥ 31402).
• Whether MSG_WTX inventory vectors are permitted (version ≥ 170014).
• Whether addrv2 messages are supported (see addrv2).
• Whether the peer meets the minimum version requirements for the current network epoch (see Network Upgrade Epoch Enforcement).

Note that "the protocol version" as used in this document refers to the negotiated protocol version unless otherwise specified. A node's advertised protocol version is the version it includes in its version message.

Version Message

The version message payload has the following format:

The addr_recv and addr_from fields use the CAddress encoding without the time field, regardless of the protocol version being negotiated.

The nonce field is used for self-connection detection. If a node receives a version message containing its own nonce, it MUST close the connection.

The user_agent string MUST NOT exceed 256 bytes. A node SHOULD disconnect peers that send a longer user agent.

The relay field is optional; if not present, its value MUST be interpreted as true. A node SHOULD reject version messages in which the relay field is present with a value other than 0 or 1. Nodes SHOULD create version messages with this field present.

Version Validation

A receiving node MUST validate the version message as follows:

• The version field MUST be at least 170002 (MIN_PEER_PROTO_VERSION).
• On Testnet, the version field MUST be at least 170040 (MIN_TESTNET_PEER_PROTO_VERSION).
• The version field MUST be at least the protocol version associated with the current network epoch (see Network Upgrade Peer Management).
• The nonce MUST NOT match the local node's nonce (self-connection detection).
• A peer MUST NOT send more than one version message per connection. Duplicate version messages incur a misbehavior penalty.

If any of these checks fail, the node MUST disconnect the peer. A reject message with code REJECT_OBSOLETE (0x11) SHOULD be sent before disconnecting for version-related failures.

Protocol Versioning

Protocol versions are 32-bit integers. The following versions are significant:

Network Upgrade Epoch Enforcement

Each network upgrade defines a minimum protocol version. When a network upgrade activates (as defined in ZIP 200¹⁵), a node MUST disconnect any peer whose negotiated protocol version is less than the protocol version associated with the current epoch. The node SHOULD send a reject message with code REJECT_OBSOLETE (0x11) before disconnecting.

The following protocol versions are associated with network upgrades on Mainnet:

The following protocol versions are associated with network upgrades on Testnet:

Note that Testnet protocol versions differ from Mainnet for several upgrades (Overwinter, Blossom, Heartwood, Canopy, NU5, NU6, and NU6.1), but coincide for Sapling, NU6.2, and NU6.3. The coincidences for NU6.2 and NU6.3 are a consequence of the ad hoc assignment used through NU6.3; see Assigning Protocol Versions to Network Upgrades for the rule adopted to prevent such coincidences from NU7 onward.

Assigning Protocol Versions to Network Upgrades

When a new network upgrade is defined, it is assigned a protocol version for each network on which it will activate. In the tables above, the Mainnet protocol version and Testnet protocol version of an upgrade are the values in the Mainnet and Testnet tables respectively; Regtest uses the Testnet protocol version. These assignments MUST satisfy the following invariants:

1. Zcash range. Every assigned protocol version is of the form 170000 + n with 0 ≤ n ≤ 999. The leading 170 distinguishes Zcash protocol versions from those of Bitcoin Core, from which the version message format is inherited. When this range nears exhaustion, a successor scheme will need to be specified.
2. Per-network monotonicity. For a given network, the protocol version assigned to an upgrade MUST be strictly greater than any preceding protocol version assigned to that network. This is what allows a node to reject peers that have not upgraded (see Network Upgrade Epoch Enforcement).

Through NU6.3, protocol versions were assigned by hand and do not follow a single rule; in particular the Testnet and Mainnet protocol versions of NU6.2 and NU6.3 are equal (170150 and 170160 respectively), so those values do not by themselves identify a network. From NU7 onward, protocol versions MUST be assigned by the following procedure, which preserves the invariants above and additionally guarantees that no protocol version is ever assigned to more than one (network, upgrade) pair:

Let M be the Mainnet protocol version of the immediately preceding upgrade, and let base be the least value of the form 170000 + 20·k that is strictly greater than M. Then the Testnet protocol version of the new upgrade is base, and its Mainnet protocol version is base + 10.

Equivalently, from NU7 onward Testnet protocol versions are congruent to 0 modulo 20 and Mainnet protocol versions are congruent to 10 modulo 20, so the two never coincide.

For example, the preceding Mainnet protocol version at NU7 is NU6.3's 170160; the least 170000 + 20·k strictly greater than 170160 is 170180, so NU7 is assigned Testnet protocol version 170180 and Mainnet protocol version 170190. The upgrade following NU7 would then be assigned 170200 (Testnet) and 170210 (Mainnet).

Message Types

This section defines each protocol message. For each message, the command string, direction, payload format, and semantics are specified.

Control Messages

version

Command

version

Direction

Both (sent by each side during handshake)

Payload

See Version Message.

Initiates the connection handshake. The details of this message are specified in Connection Handshake.

verack

Command

verack

Direction

Both

Payload

Empty (0 bytes).

Acknowledges receipt of a version message. After exchanging version and verack messages, the connection is considered established.

ping

Command

ping

Direction

Both

Payload

Size	Field	Description
8	nonce	Random value (uint64).

Sent periodically to measure latency and detect dead connections. The zcashd implementation sends ping messages every 120 seconds (PING_INTERVAL); the Zebra implementation uses a 59-second heartbeat interval (HEARTBEAT_INTERVAL). The receiving node MUST respond with a pong message containing the same nonce.

pong

Command

pong

Direction

Both

Payload

Size	Field	Description
8	nonce	The nonce from the corresponding ping message (uint64).

Sent in response to a ping. The nonce MUST match the nonce from the ping that is being responded to.

reject

Command

reject

Direction

Both

Payload

Size	Field	Description
varies	message	The command string of the rejected message (CompactSize-prefixed string).
1	ccode	Reject code (uint8). See Reject Codes.
varies	reason	Human-readable rejection reason (CompactSize-prefixed string).
0 or 32	data	Optional. For tx and block rejections, the 32-byte hash of the rejected object.

Notifies the peer of a rejected message. This message is informational; receipt of a reject message does not require any specific action by the receiving node.

alert

Command

alert

Direction

Both

Payload

Size	Field	Description
varies	payload	Serialized alert data (CompactSize-prefixed byte vector).
varies	signature	ECDSA signature over the payload (CompactSize-prefixed byte vector).

The serialized alert data contains:

Size	Field	Description
4	version	Alert format version (int32).
8	relay_until	Timestamp after which nodes should stop relaying (int64).
8	expiration	Timestamp after which the alert is no longer in effect (int64).
4	id	Unique alert identifier (int32).
4	cancel	ID of a previous alert to cancel (int32).
varies	set_cancel	Set of alert IDs to cancel (CompactSize-prefixed vector of int32).
4	min_ver	Minimum applicable client version (int32).
4	max_ver	Maximum applicable client version (int32).
varies	set_sub_ver	Set of applicable user agent substrings (CompactSize-prefixed vector of strings).
4	priority	Alert priority (int32).
varies	comment	Comment for operators (CompactSize-prefixed string, max 65536 bytes).
varies	status_bar	Status bar message (CompactSize-prefixed string, max 256 bytes).
varies	rpc_error	RPC error message (CompactSize-prefixed string, max 256 bytes).

The alert message is deprecated. It is documented here for completeness, as it remains part of the zcashd implementation but has been proposed for removal ¹⁷, and implementations MAY choose not to support it. Nodes that do support alert messages SHOULD validate the alert signature against the network's alert public key before processing or relaying alerts.

Address Messages

addr

Command

addr

Direction

Both

Payload

Size	Field	Description
varies	count	Number of addresses (CompactSize).
varies	addr_list	List of CAddress entries (with time field).

The count MUST NOT exceed 1000. A node receiving an addr message with more than 1000 entries SHOULD assign a misbehavior penalty of 20 points to the sending peer.

getaddr

Command

getaddr

Direction

Both (but typically only sent to inbound peers)

Payload

Empty (0 bytes).

Requests peer addresses from the remote node. The remote node responds by sending one or more addr messages. A node SHOULD only send getaddr once per connection, and SHOULD only process getaddr from inbound peers to prevent address-based fingerprinting attacks.

addrv2

Command

addrv2

Direction

Both

Payload

Size	Field	Description
varies	count	Number of addresses (CompactSize).
varies	addr_list	List of address entries in addrv2 format (see below).

Each address entry has the following format:

Size	Field	Description
4	time	Unix-epoch UTC time in seconds when the node was last seen (uint32, little-endian).
varies	services	Service bits (CompactSize-encoded uint64).
1	networkID	Network identifier (uint8).
varies	sizeAddr	Length of addr in bytes (CompactSize).
varies	addr	Network address (sizeAddr bytes). Interpretation depends on networkID.
2	port	Network port (uint16, big-endian). MUST be 0 if not relevant for the network.

The count MUST NOT exceed 1000. A node MUST reject messages with more than 1000 addresses.

The addr field MUST NOT exceed 512 bytes. A node MUST reject messages with a longer addr field, irrespective of the network ID.

The services field is encoded as a CompactSize, unlike the fixed 8-byte uint64 encoding used in addr messages. This makes the common case (few service bits) more compact.

The following network IDs are defined:

Network ID	Name	Address Size	Description
0x01	IPV4	4 bytes	IPv4 address.
0x02	IPV6	16 bytes	IPv6 address.
0x04	TORV3	32 bytes	Tor v3 onion service address (Ed25519 public key).
0x05	I2P	32 bytes	I2P overlay network address (SHA-256 hash).
0x06	CJDNS	16 bytes	Cjdns overlay network address (IPv6 in fc00::/8).

Network ID 0x03 is reserved (it was assigned to Tor v2 in BIP 155¹⁸, but Tor v2 addresses are no longer supported and MUST NOT be used).

A node MUST reject addresses whose length does not match the expected length for the given network ID. A node MUST NOT gossip addresses with unrecognized network IDs.

IPV4 and IPV6 addresses are encoded in network byte order (big-endian). TORV3 addresses consist of the 32-byte Ed25519 master public key of the onion service. I2P addresses consist of the decoded 32-byte SHA-256 hash. CJDNS addresses are 16-byte IPv6 addresses in the fc00::/8 range, encoded in network byte order.

Deployment: Unlike BIP 155¹⁹, which uses a sendaddrv2 handshake message, Zcash signals addrv2 support through protocol version negotiation, as specified in ZIP 155²⁰. The deployment version has not yet been assigned; see ZIP 155 for the status of this assignment. A node MUST NOT send addrv2 messages on connections where the negotiated protocol version is below the deployment threshold. A node that supports addrv2 MAY still send addr messages on any connection.

The full specification of the addrv2 message, including network address encoding details, is given in ZIP 155²¹.

Inventory Messages

inv

Command

inv

Direction

Both

Payload

Size	Field	Description
varies	count	Number of inventory vectors (CompactSize).
varies	inventory	List of inventory vectors (see Inventory Vectors).

Announces one or more objects (transactions or blocks) that the sender has available. The count MUST NOT exceed 50,000. A node receiving an inv message with more than 50,000 entries SHOULD assign a misbehavior penalty of 20 points.

getdata

Command

getdata

Direction

Both

Payload

Size	Field	Description
varies	count	Number of inventory vectors (CompactSize).
varies	inventory	List of inventory vectors (see Inventory Vectors).

Requests one or more objects from the remote peer. The count MUST NOT exceed 50,000. A node receiving a getdata message with more than 50,000 entries MUST assign a misbehavior penalty of 20 points.

If the requested object is not available, the receiving node SHOULD respond with a notfound message.

notfound

Command

notfound

Direction

Both

Payload

Size	Field	Description
varies	count	Number of inventory vectors (CompactSize).
varies	inventory	List of inventory vectors identifying objects not found.

Sent in response to a getdata message for objects that the node does not have.

Block Messages

getblocks

Command

getblocks

Direction

Both

Payload

Size	Field	Description
4	version	Protocol version (uint32).
varies	block_locator_count	Number of block locator hashes (CompactSize).
varies	block_locator_hashes	Block locator hashes (each 32 bytes), from highest to lowest height.
32	hash_stop	Hash of the last desired block, or all zeros to request as many as possible.

Requests an inv message containing block hashes starting after the first block locator hash found in the responder's best chain, up to and including hash_stop or 500 blocks, whichever comes first. A node MUST NOT return more than 500 blocks.

getheaders

Command

getheaders

Direction

Both

Payload

Size	Field	Description
4	version	Protocol version (uint32).
varies	block_locator_count	Number of block locator hashes (CompactSize).
varies	block_locator_hashes	Block locator hashes (each 32 bytes), from highest to lowest height.
32	hash_stop	Hash of the last desired header, or all zeros to request as many as possible.

Requests a headers message containing block headers starting after the first block locator hash found in the responder's best chain, up to and including hash_stop or 160 headers, whichever comes first. A node MUST NOT return more than 160 headers (MAX_HEADERS_RESULTS).

headers

Command

headers

Direction

Both

Payload

Size	Field	Description
varies	count	Number of headers (CompactSize).
varies	headers	Block headers. Each header is followed by a transaction count field (CompactSize, always 0 in headers messages).

The count MUST NOT exceed 160. The headers MUST form a contiguous chain (each header's hashPrevBlock must match the hash of the preceding header). A node receiving non-contiguous headers SHOULD assign a misbehavior penalty of 20 points.

For the encoding of block headers, see the Zcash Protocol Specification ²².

block

Command

block

Direction

Both

Payload

A single serialized block.

Sent in response to a getdata request for a MSG_BLOCK inventory entry. For the encoding of blocks, see the Zcash Protocol Specification²³.

Transaction Messages

tx

Command

tx

Direction

Both

Payload

A single serialized transaction.

Sent in response to a getdata request for a MSG_TX or MSG_WTX inventory entry. For the encoding of transactions, see the Zcash Protocol Specification ²⁴.

Bloom Filter Messages

These messages implement BIP 37²⁵ Bloom filtering. As of protocol version 170004, a node MUST NOT send Bloom filter commands to a peer that does not advertise NODE_BLOOM in its service flags. Sending Bloom filter commands to a peer that does not advertise NODE_BLOOM SHOULD incur a misbehavior penalty of 100 points (immediate ban).

filterload

Command

filterload

Direction

Both

Payload

A serialized Bloom filter, as defined in BIP 37²⁶.

Sets a Bloom filter on the connection. After a filter is set, the peer will only relay transactions that match the filter.

filteradd

Command

filteradd

Direction

Both

Payload

Size	Field	Description
varies	data	Element to add to the Bloom filter (CompactSize-prefixed, max 520 bytes).

Adds an element to the existing Bloom filter. The data MUST NOT exceed 520 bytes. A node receiving data exceeding 520 bytes SHOULD assign a misbehavior penalty of 100 points.

filterclear

Command

filterclear

Direction

Both

Payload

Empty (0 bytes).

Removes the Bloom filter from the connection. Transaction relay resumes normally.

Memory Pool

mempool

Command

mempool

Direction

Both

Payload

Empty (0 bytes).

Requests the contents of the peer's transaction memory pool. The peer responds by sending one or more inv messages listing the transactions in its mempool.

Block Relay

Headers-First Synchronization

Nodes MAY synchronize the block chain using a headers-first approach. The Zebra implementation uses headers-first synchronization; zcashd does not²⁷.

1. The synchronizing node sends a getheaders message with a block locator.
2. The remote peer responds with a headers message containing up to 160 headers.
3. The synchronizing node validates the headers and requests full blocks via getdata with MSG_BLOCK inventory entries.
4. Steps 1–3 repeat until the node is synchronized with the network.

Block Download Parameters

• Download window: A node SHOULD NOT request blocks more than 1024 blocks ahead of its current validated tip (BLOCK_DOWNLOAD_WINDOW).
• Per-peer limit: A node SHOULD NOT have more than 16 blocks in transit from a single peer simultaneously (MAX_BLOCKS_IN_TRANSIT_PER_PEER).
• Stalling timeout: If a peer has not delivered a requested block within 2 seconds (BLOCK_STALLING_TIMEOUT) and there are other peers available with the same block, the node MAY request the block from an alternative peer.
• Maximum headers per response: 160 (MAX_HEADERS_RESULTS).

Block Announcement

Blocks are announced immediately via inv messages; they are not subject to the trickling delay applied to transactions.

Transaction Relay

Inventory-Based Relay

Transaction relay follows an inventory-based protocol:

1. A node with a new transaction sends an inv message to its peers.
2. Peers that want the transaction respond with a getdata message.
3. The originating node sends the transaction in a tx message.

Transactions with version ≤ 4 MUST be announced using MSG_TX inventory vectors. Transactions with version ≥ 5 MUST be announced using MSG_WTX inventory vectors. Using the wrong inventory type for a transaction version SHOULD incur a misbehavior penalty. See ZIP 239²⁸.

Trickling

To impede network topology inference, transaction inventory SHOULD NOT be sent immediately but SHOULD instead be "trickled" at random intervals. The specific trickling parameters are implementation-defined. The zcashd implementation uses the following values:

• The average broadcast interval is 5 seconds (INVENTORY_BROADCAST_INTERVAL).
• For outbound peers, the effective interval in seconds is halved rounding down (2 seconds on average).
• At most 35 inventory entries (INVENTORY_BROADCAST_MAX) are sent per trickle interval.
• Broadcast times follow a Poisson distribution centered on the broadcast interval.

The Zebra implementation uses a 7-second gossip delay (PEER_GOSSIP_DELAY).

Transaction Expiry

A node SHOULD NOT relay a transaction that will expire within 3 blocks of its view of the current chain tip (TX_EXPIRING_SOON_THRESHOLD).

Orphan Transactions

An orphan transaction is one that references inputs from unknown parent transactions.

• A node SHOULD store at most 100 orphan transactions (DEFAULT_MAX_ORPHAN_TRANSACTIONS).
• Orphan transactions expire and are removed after 1200 seconds (20 minutes, ORPHAN_TX_EXPIRE_TIME).
• Only fully transparent transactions are eligible for orphan storage.
• When the orphan pool is full, the oldest orphan transactions are evicted.

Relay Fee

Transactions are subject to a minimum relay fee. Both the zcashd and Zebra implementations use a base rate of 100 zatoshis per 1000 bytes (DEFAULT_MIN_RELAY_TX_FEE), though the zcashd implementation applies additional logic for low-fee and free transactions²⁹. A node SHOULD NOT relay transactions with fees below its minimum relay fee threshold.

Address Relay

Address relay allows nodes to discover peers by propagating CAddress records through the network.

Rate Limiting

Address records SHOULD be subject to rate limiting to prevent address flooding. The specific rate-limiting mechanism is implementation-defined. The zcashd-specific rate-limiting mechanism uses a token-bucket algorithm:

• Rate: 0.1 address records per second per peer (MAX_ADDR_RATE_PER_SECOND).
• Bucket capacity: 1000 (MAX_ADDR_PROCESSING_TOKEN_BUCKET), replenished at 0.1 tokens per second.
• Upon receiving a getaddr response, 1000 tokens (MAX_ADDR_TO_SEND) are added to the bucket, exempt from the soft limit.
• Whitelisted peers bypass address rate limiting.

Address Broadcasting

The specific broadcast intervals are implementation-defined. The zcashd implementation uses the following values:

• Addresses are broadcast to peers at an average interval of 30 seconds (AVG_ADDRESS_BROADCAST_INTERVAL).
• A node's own address is broadcast approximately every 9.6 hours (AVG_LOCAL_ADDRESS_BROADCAST_INTERVAL = 24 * 24 * 60 = 34560 seconds).

Misbehavior and Banning

Nodes SHOULD track misbehavior scores for each connected peer. The zcashd implementation bans a peer when its cumulative score reaches or exceeds 100 (DEFAULT_BANSCORE_THRESHOLD), with bans lasting 24 hours (DEFAULT_MISBEHAVING_BANTIME). The Zebra implementation also uses a threshold of 100 (MAX_PEER_MISBEHAVIOR_SCORE) but bans persist indefinitely. The ban threshold and duration are implementation-defined.

Whitelisted peers accumulate misbehavior scores but are exempt from banning.

The following table lists the misbehavior penalties assigned for specific protocol violations:

Network Upgrade Peer Management

Network upgrade peer management is specified in ZIP 201³¹. This section summarizes the key behaviors.

Pre-Activation

In the 1728-block window (NETWORK_UPGRADE_PEER_PREFERENCE_BLOCK_PERIOD) before a network upgrade activation height, a node SHOULD preferentially connect to peers that advertise a protocol version at or above the version required by the upcoming upgrade. This period corresponds to approximately 1.5 days at the post-Blossom block interval.

Post-Activation

After a network upgrade activates, a node MUST disconnect any peer whose negotiated protocol version is below the version required by the active epoch. The node SHOULD send a reject message with code REJECT_OBSOLETE (0x11) before disconnecting.

Reject Codes

Formal Model

A TLA+ formal specification of the connection lifecycle described in this ZIP is available at³². The model covers the handshake, keepalive, block synchronization, and disconnection phases, verifying liveness (all peers eventually reach the same block height) and safety (message size bounds hold across all reachable states).