Previous: Cross-Chain and Assets | Next: Security and Limitations
This document defines the logical communication protocol between participants.
All operations are defined as semantic protocol operations, independent of transport technologies such as WebSocket or gRPC.
Participants exchange protocol messages to advance state, manage channels, and coordinate operations. This document defines the structure and semantics of those messages.
The protocol assumes the following about the communication channel:
- Messages are delivered reliably (no silent loss)
- Messages are delivered in order between any two participants
- The transport supports bidirectional message exchange
The protocol does not require a specific transport technology.
All protocol messages share a common envelope structure.
| Field | Description |
|---|---|
| Type | Message type (request, response, event, or error) |
| RequestId | Numeric identifier unique within the connection |
| Method | Operation name identifying the requested action |
| Payload | Type-specific message data |
| Timestamp | Time the message was created, in milliseconds |
Messages are encoded as compact ordered arrays: [Type, RequestId, Method, Payload, Timestamp].
| Type |
|---|
| Request |
| Successful response |
| Event notification |
| Error response |
The protocol defines the following core operations:
| Operation | Direction | Description |
|---|---|---|
| RequestCreation | User → Node | Request to create a new channel |
| SubmitState | User → Node | Submit a signed state transition |
| GetLatestState | User → Node | Retrieve the current state for a channel |
| GetHomeChannel | User → Node | Retrieve on-chain home channel data |
| GetEscrowChannel | User → Node | Retrieve on-chain escrow channel data |
Creates a new channel with an initial state.
The request MUST include the channel definition parameters, the initial state and the user's signature over it. The node validates the channel definition, computes the channel identifier, verifies the user's signature, co-signs the state, and stores the channel record.
The response includes Node's signature over the submitted state.
Submits a user-signed state transition for processing.
The request MUST include the signed state with a valid transition. The node validates the state against advancement rules, verifies the user's signature, co-signs the state, and applies any side effects (e.g. scheduling blockchain operations for non-OPERATE intents, creating receiver states for transfers).
The response includes Node's signature over the submitted state.
Retrieves the current state for a given user and asset.
The response includes the latest state. Implementations MAY support filtering to return only mutually signed states.
Retrieves the on-chain home channel data for a given user and asset.
Retrieves the on-chain escrow channel data for a given escrow channel identifier.
The event message system is reserved for future specification. Events are asynchronous notifications generated by the protocol and are not responses to specific requests.
Responses are correlated with requests using the RequestId field.
Rules:
- Each request MUST include a RequestId unique within the connection
- The corresponding response MUST include the same RequestId
Errors are communicated through error response messages.
Rules:
- Every failed operation MUST return an error response
- The error payload MUST contain a human-readable error message
- Errors MUST NOT expose internal implementation details
Message ordering requirements MAY depend on the implementation. The following constraints apply at the protocol level:
- RequestId values MUST NOT be reused within a single connection
- Events MAY arrive at any time and MUST NOT block request processing
State update ordering (version sequencing) is governed by the Channel Protocol and is not a concern of the message transport layer.
Previous: Cross-Chain and Assets | Next: Security and Limitations