Bolt Protocol

Traverse implements the Bolt protocol (versions 5.1 through 6.0) for binary client-server communication.

Supported Versions

Handshake

The Bolt handshake begins with a 4-byte magic preamble:

60 60 B0 17

The client then sends four 32-bit version proposals. Each proposal is range-encoded in big-endian byte order:

[padding:8, range:8, minor:8, major:8]

  padding (bits 24-31): always 0
  range   (bits 16-23): number of minor versions backward from "minor" that are accepted
  minor   (bits  8-15): minor version
  major   (bits  0-7):  major version

The server iterates proposals in order, tries each version in the range, and responds with the highest mutually supported version. If no version matches, the server responds with 0.0 and closes the connection.

Default Port

Traverse listens for Bolt connections on port 7690 by default (configurable via --listen).

Authentication

After the handshake, the client sends a HELLO message followed by LOGON with credentials (Bolt 5.4+). If authentication is not configured on the server, any credentials are accepted.

Re-authentication is supported via LOGOFF + LOGON to switch users on the same connection.

TLS

When the server is started with --tls-cert and --tls-key, Bolt connections are upgraded to TLS. Drivers connect using the bolt+s:// scheme:

bolt+s://localhost:7690

Transactions

Bolt supports explicit transactions via BEGIN, COMMIT, and ROLLBACK messages. Queries outside an explicit transaction run in auto-commit mode.

Features

• Streaming results - rows sent as individual RECORD messages
• Query parameters - safe parameterized queries to prevent injection
• Bookmarks - causal consistency across sessions
• Query statistics - nodes created, relationships created, properties set, labels added, etc.
• Notifications - warnings and informational messages from the server
• Telemetry - client API type telemetry (Bolt 5.4+)
• RESET - connection health recovery
• Rich failure metadata (0.8.0) - Bolt 5.7+ FAILURE fields including GQL status codes, with IGNORED correctly emitted for messages after a failure
• Retry classification (0.8.0) - query timeouts and memory aborts are classified as TransientError, so drivers' retry policies engage instead of failing hard
• Mid-stream error delivery (0.8.0) - errors during result streaming arrive as FAILURE messages on the live connection rather than a connection teardown

Driver Compatibility

Any Bolt driver supporting version 5.1 or later works with Traverse. Tested drivers include:

Genuine-Neo4j Client Check

Some Bolt clients - including G.V() (gdotv.com) and libraries like py2neo - verify that the server identifies as a genuine Neo4j instance and refuse to connect otherwise ("Server does not identify as a genuine Neo4j instance"). Start Traverse with --server-agent "Neo4j/5.26.0" (or set TRAVERSE_SERVER_AGENT) to advertise a Neo4j-style agent string. For G.V(), also pick Neo4j as the database type in the connection dialog. See Client Compatibility.