Protocol V3 - Transaction Support

Purpose and Scope

This document describes Protocol Version 3 of the Bolt wire protocol, which introduced explicit transaction control through the BEGIN, COMMIT, and ROLLBACK messages. V3 also replaced the INIT message with HELLO and added GOODBYE for clean connection termination.

For information about the foundational V1 and V2 protocols, see Protocol V1 and V2 - Foundation. For the V4 series which adds granular streaming, see Protocol V4.x Series - Streaming and Routing.

---

Overview of Protocol V3 Changes

Protocol V3 was introduced to provide explicit transaction boundaries, replacing the implicit auto-commit behavior of V1. This version maintains backward compatibility with V1's result streaming approach (PULL_ALL/DISCARD_ALL) while adding transaction lifecycle management.

Message Changes from V1 to V3

V1 Message	V3 Equivalent	Notes
INIT	HELLO	Authentication now uses HELLO with structured parameters
-	BEGIN	New: Start explicit transaction
-	COMMIT	New: Commit transaction
-	ROLLBACK	New: Rollback transaction
RUN	RUN (enhanced)	Now accepts optional extra parameter for transaction metadata
PULL_ALL	PULL_ALL	Unchanged from V1
DISCARD_ALL	DISCARD_ALL	Unchanged from V1
RESET	RESET	Unchanged from V1
ACK_FAILURE	Removed	No longer required in V3
-	GOODBYE	New: Clean connection termination

Sources: src/protocol/V1.php1-24 src/protocol/V3.php1-29

---

Protocol V3 Implementation Structure

The V3 protocol class composes functionality from multiple trait sources:

Sources: src/protocol/V3.php1-29 src/protocol/v1/AvailableStructures.php src/protocol/v3/ServerStateTransition.php

---

Authentication: HELLO Message

V3 replaces V1's INIT message with HELLO, which provides a more structured approach to authentication. The HELLO message is sent immediately after protocol version negotiation.

HELLO Message Signature

Message Code: 0x01
Parameters: Map of authentication and connection metadata

Implementation

The HelloMessage trait provides the hello() method:

src/protocol/v3/HelloMessage.php1-24

Expected Parameters

The $extra array typically includes:

Parameter	Type	Required	Description
user_agent	string	Yes	Client identification string
scheme	string	Yes	Authentication scheme (e.g., "basic")
principal	string	Yes	Username
credentials	string	Yes	Password or token
routing	object	No	Routing context for clusters

State Transition

• Allowed State: CONNECTED
• Success: Transitions to READY
• Failure: Transitions to DEFUNCT

Sources: src/protocol/v3/HelloMessage.php1-24 tests/protocol/V3Test.php27-65

---

Transaction Support: Core Feature of V3

Protocol V3 introduces explicit transaction control, allowing applications to group multiple queries into atomic units. This is the primary feature that distinguishes V3 from V1.

Transaction Lifecycle

Sources: tests/protocol/V3Test.php115-171

---

BEGIN Message

The BEGIN message initiates an explicit transaction, transitioning the server from READY to TX_READY state.

Message Signature

Message Code: 0x11
Parameters: Map of optional transaction metadata

Implementation

src/protocol/v3/BeginMessage.php1-23

Optional Transaction Metadata

The $extra array can include:

Parameter	Type	Description
tx_timeout	integer	Transaction timeout in milliseconds
tx_metadata	object	Custom metadata attached to transaction
mode	string	Access mode: "r" (read) or "w" (write)
db	string	Target database name (multi-database)

State Transition

• Allowed State: READY
• Success: Transitions to TX_READY
• Failure: Transitions to FAILED
• Interrupted: Stays in INTERRUPTED, returns IGNORED

Response Handling

The server responds with SUCCESS containing transaction metadata. The protocol automatically tracks the transaction state through the serverState property.

Sources: src/protocol/v3/BeginMessage.php1-23 tests/protocol/V3Test.php115-141

---

COMMIT Message

The COMMIT message finalizes an explicit transaction, applying all changes to the database.

Message Signature

Message Code: 0x12
Parameters: None

Implementation

src/protocol/v3/CommitMessage.php1-36

State Transition

• Allowed State: TX_READY
• Success: Transitions to READY, resets openStreams to 0
• Failure: Transitions to FAILED
• Interrupted: Stays in INTERRUPTED, returns IGNORED

Behavior Notes

• All pending result streams are automatically closed
• The openStreams counter is reset to ensure clean state
• The transaction must not have any active streaming operations (all PULL_ALL operations must complete)

Sources: src/protocol/v3/CommitMessage.php1-36 tests/protocol/V3Test.php146-171

---

ROLLBACK Message

The ROLLBACK message aborts an explicit transaction, discarding all changes made within it.

Message Signature

Message Code: 0x13
Parameters: None

Implementation

src/protocol/v3/RollbackMessage.php1-36

State Transition

• Allowed State: TX_READY
• Success: Transitions to READY, resets openStreams to 0
• Failure: Transitions to FAILED
• Interrupted: Stays in INTERRUPTED, returns IGNORED

Use Cases

• Error recovery: Roll back when a query fails
• Business logic: Cancel transaction based on application conditions
• Connection reset: Clean up on connection issues

Sources: src/protocol/v3/RollbackMessage.php1-36 tests/protocol/V3Test.php176-201

---

RUN Message in V3

V3 enhances the RUN message from V1 by adding an optional extra parameter for transaction-specific metadata and query configuration.

Message Signature

Message Code: 0x10
Parameters:

1. Query string
2. Parameters object
3. Extra metadata object (new in V3)

Implementation

src/protocol/v3/RunMessage.php1-42

Extra Parameters

Parameter	Type	Description
tx_timeout	integer	Query timeout in milliseconds
tx_metadata	object	Custom metadata for this query
mode	string	Access mode: "r" or "w"
db	string	Target database name
bookmarks	array	Causal consistency bookmarks

Usage in Transactions vs Auto-Commit

In Transaction (TX_READY state):

• RUN executes within the current transaction
• Changes are not committed until COMMIT is called
• Multiple RUN operations can be executed sequentially

In Auto-Commit (READY state):

• RUN executes as a single-query transaction
• Changes are automatically committed after result consumption
• Similar to V1 behavior

Response Behavior

The _run() response handler checks for the qid field to track streaming state:

src/protocol/v3/RunMessage.php35-41

Sources: src/protocol/v3/RunMessage.php1-42 tests/protocol/V3Test.php70-110

---

Server State Transitions in V3

V3 introduces a new TX_READY state to track when a transaction is active. This state is critical for ensuring proper transaction semantics.

V3 State Machine

State Transition Summary

From State	Message	Success →	Failure →
CONNECTED	HELLO	READY	DEFUNCT
READY	BEGIN	TX_READY	FAILED
READY	RUN	STREAMING	FAILED
STREAMING	PULL_ALL	READY	FAILED
TX_READY	RUN	TX_STREAMING	FAILED
TX_READY	COMMIT	READY	FAILED
TX_READY	ROLLBACK	READY	FAILED
TX_STREAMING	PULL_ALL	TX_READY	FAILED
FAILED	RESET	READY	DEFUNCT

Sources: src/protocol/v3/ServerStateTransition.php tests/protocol/V3Test.php1-218

---

GOODBYE Message

V3 introduces GOODBYE for graceful connection termination, allowing the client to signal clean shutdown before closing the socket.

Message Signature

Message Code: 0x02
Parameters: None

Implementation

src/protocol/v3/GoodbyeMessage.php

The GOODBYE message is sent without expecting a response. After sending, the server state immediately transitions to DEFUNCT and the connection should be closed.

Usage Pattern

State Transition

• Allowed State: Any state
• After Send: Transitions to DEFUNCT
• No Response Expected: The server may close the connection immediately

This differs from RESET, which attempts to recover the connection to a usable state. GOODBYE explicitly signals that no further communication will occur.

Sources: src/protocol/v3/GoodbyeMessage.php tests/protocol/V3Test.php206-216

---

Removed Features from V1

Protocol V3 removes the ACK_FAILURE message that was present in V1. This simplifies error handling as the server automatically transitions to appropriate states without requiring explicit acknowledgment.

ACK_FAILURE (V1 Only)

In V1, when a FAILURE occurred, the client had to send ACK_FAILURE before the server would accept new messages. This has been removed in V3:

• V1 Error Flow: FAILURE → ACK_FAILURE → continue
• V3 Error Flow: FAILURE → RESET → continue

The RESET message now serves the dual purpose of recovering from errors and resetting state.

Sources: src/protocol/V1.php1-24 src/protocol/v1/AckFailureMessage.php1-24

---

Compatibility and Migration from V1

Protocol Selection

V3 is automatically selected during protocol version negotiation if supported by both client and server. Applications using the Bolt client do not need to change code when upgrading from V1 to V3, unless they want to use transactions.

Auto-Commit Mode Compatibility

V3 maintains full compatibility with V1's auto-commit behavior:

Transaction Mode (V3 Only)

Message Pipelining

V3 fully supports message pipelining, allowing multiple messages to be sent before reading responses:

Sources: tests/protocol/V3Test.php1-218 src/protocol/AProtocol.php

---

Protocol Version Availability

Protocol V3 is supported by:

• Neo4j: Versions 3.5.x and 4.0.x
• Memgraph: Legacy versions (newer versions use V4+)

For newer features like granular streaming (PULL/DISCARD with batch sizes), upgrade to Protocol V4 or later. See Protocol V4.x Series - Streaming and Routing for details.

Sources: README.md GitHub Actions test matrix configuration