Skip to content

[ZIP 204] Draft specification of the Zcash P2P network protocol#1174

Merged
daira merged 7 commits intomainfrom
zip-0204
Feb 11, 2026
Merged

[ZIP 204] Draft specification of the Zcash P2P network protocol#1174
daira merged 7 commits intomainfrom
zip-0204

Conversation

@nuttycom
Copy link
Copy Markdown
Contributor

@nuttycom nuttycom commented Feb 6, 2026

Replaces the Reserved stub with a comprehensive specification covering message framing, connection handshake, all 19 message types, block and transaction relay, peer discovery, misbehavior scoring, and network upgrade peer management. All constants derived from the zcashd reference implementation.

Fixes #352

@nuttycom nuttycom changed the title ZIP 204: Draft specification of the Zcash P2P network protocol [ZIP 204] Draft specification of the Zcash P2P network protocol Feb 6, 2026
@nuttycom nuttycom requested a review from daira February 6, 2026 14:41
@nuttycom nuttycom force-pushed the zip-0204 branch 2 times, most recently from 4114c46 to 8596b11 Compare February 6, 2026 20:28
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst
Comment thread zips/zip-0204.rst
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst
Comment thread zips/zip-0204.rst
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
daira
daira previously approved these changes Feb 10, 2026
Copy link
Copy Markdown
Collaborator

@daira daira left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK with suggestions.

Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst
Comment thread zips/zip-0204.rst
| | | transaction relay. See ZIP 239 |
| | | [#zip-0239]_. |
+---------+-------------------------------------+------------------------------------------+
| 170040 | ``MIN_TESTNET_PEER_PROTO_VERSION`` | Minimum protocol version for Testnet |
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 170040 | ``MIN_TESTNET_PEER_PROTO_VERSION`` | Minimum protocol version for Testnet |
| 170030 | ``MIN_TESTNET_PEER_PROTO_VERSION`` | Minimum protocol version for Testnet |

This is currently implemented as 170110 and 170120 in Zebra right now (for NU6)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hm, wasn't it updated for NU6.1? Does that mean that unmodified NU6 peers will still be connecting to the NU6.1 testnet?

Copy link
Copy Markdown
Collaborator

@daira daira Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MIN*_PEER_PROTOCOL_VERSION constants are an initial check on connections, they are not what causes clients with version too low for the current epoch to be dropped. So they will be connecting and then getting dropped. I was at some point arguing for these constants to be raised more aggressively and the handshake simplified, but the latter wasn't a high priority and the former didn't make much difference on its own.

arya2
arya2 previously approved these changes Feb 10, 2026
Comment thread zips/zip-0204.rst Outdated
@nuttycom nuttycom dismissed stale reviews from arya2 and daira via bda1054 February 10, 2026 22:41
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst
Comment thread zips/zip-0204.rst Outdated
Comment thread zips/zip-0204.rst Outdated
nuttycom and others added 7 commits February 10, 2026 16:28
Replaces the Reserved stub with a comprehensive specification covering
message framing, connection handshake, all 19 message types, block and
transaction relay, peer discovery, misbehavior scoring, and network
upgrade peer management. All constants derived from the zcashd reference
implementation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Fix "order of preference" phrasing for peer discovery mechanisms
- Replace "zcashd reference implementation" with "zcashd implementation"
  throughout and document Zebra's corresponding values
- Remove integer type table (belongs in protocol spec)
- Add note that CompactSize is not formally defined in protocol spec
- Add RFC 4291 reference for IPv4-mapped IPv6 addresses
- Spell out "little-endian" instead of abbreviating "LE"
- Add Protocol Version Negotiation section to clarify ambiguous
  "the protocol version" usage
- Spell out bit numbering convention for service flags
- Add reference to zcashd PR #7039 for alert removal
- Note ZIP 155 for addrv2 deployment version assignment status

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Replace undefined ``bool`` with ``uint8``; 0 for false, 1 for true
  in the version message relay field
- Change "Unix epoch time" / "Unix timestamp" to "Unix-epoch UTC time
  in seconds" for all timestamp fields

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Revise DNS seeding to describe both zcashd and Zebra behavior
- Remove zcashd-specific SeedSpec6 reference from hardcoded seeds
- Clarify command string validation: "ignored" not "rejected"; enumerate
  all currently used command strings
- Use $k$ inline math syntax instead of :math: for service flags
- Rewrap pong timeout line with "a corresponding pong"
- Fix getblocks/getheaders descriptions: "up to and including hash_stop"
  and explicit MUST NOT limits
- Soften misbehavior penalties from MUST to SHOULD (overspecification)
- Note that zcashd does not use headers-first sync (refs zcashd#6292)
- Make MSG_TX MUST for v4 transactions (bidirectional requirement)
- "To impede" instead of "To prevent" for trickling rationale
- "halved rounding down" instead of "halved via integer right-shift"
- "its view of the current chain tip" for transaction expiry
- Remove orphan expiration check interval (overspecification)
- Simplify shielded eligibility to "fully transparent transactions"
- Document relay fee complexity with zcashd source reference
- Use "zcashd-specific rate-limiting" and "token-bucket algorithm"
- Reorder references per ZIP convention (BCP14, RFCs, protocol spec,
  ZIPs, BIPs, external)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Capitalize "Bloom" filter throughout (named after Burton Howard Bloom)
- Capitalize "Testnet" and "Mainnet" in protocol version note
- Add version validation disconnect summary to Protocol Version
  Negotiation section
- relay field: no text change needed (informational links noted)
- MSG_TX MUST for v4: already addressed in prior commit
- MIN_TESTNET_PEER_PROTO_VERSION: confirmed 170040 matches zcashd

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Zebra strictly validates that the relay field is 0 or 1; zcashd
accepts any non-zero value as true via implicit C++ bool conversion.
Use SHOULD to recommend validation without making zcashd non-conformant.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Copy link
Copy Markdown
Collaborator

@daira daira left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK

@daira daira merged commit b25176f into main Feb 11, 2026
3 checks passed
@nuttycom nuttycom deleted the zip-0204 branch February 11, 2026 14:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[ZIP 204] P2P network protocol differences from Bitcoin (version, magics, alerts, etc.)

3 participants