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.

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 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.

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 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:

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.

Network Upgrade Epoch Enforcement

Each network upgrade defines a minimum protocol version. When a network upgrade activates (as defined in ZIP 200 9), 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).

Control Messages

Address Messages

Inventory Messages

Block Messages

Transaction Messages

Bloom Filter Messages

These messages implement BIP 37 15 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).

Memory Pool

Headers-First Synchronization

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

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.

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 12.

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 20. A node SHOULD NOT relay transactions with fees below its minimum relay fee threshold.

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).

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.