NitroliteRPC
The NitroliteRPC provides a secure, reliable real-time communication protocol for state channel applications. It enables off-chain message exchange, state updates, and channel management. This system is built around the NitroliteRPC class, which provides the foundational methods for message construction, signing, parsing, and verification.
Message Creation API
Detailed reference for functions that create specific RPC request messages.
RPC Type Definitions
Comprehensive documentation of all TypeScript types and interfaces used by the RPC system.
Core Logic: The NitroliteRPC Class
The NitroliteRPC class is central to the RPC system. It offers a suite of static methods to handle the low-level details of the NitroliteRPC protocol.
Message Creation
createRequest
Constructs a standard RPC request object, forming the base structure for any request sent via the NitroliteRPC protocol.
Parameters
- requestId:
RequestID - method:
string - params:
T (unknown[]) - timestamp:
Timestamp
Returns:NitroliteRPCRequest<T>
Example
const request = NitroliteRPC.createRequest(1, "get_config", [], Date.now());
createAppRequest
Constructs an RPC request object specifically scoped to an application, including application ID and optional intent.
Parameters
- requestId:
RequestID - method:
string - params:
T (unknown[]) - timestamp:
Timestamp - appId:
AccountID - intent:
Intent
Returns:NitroliteRPCRequest<T>
Example
const appRequest = NitroliteRPC.createAppRequest(1, "app_update", [{data: "0x123"}], Date.now(), "app_0xabc", Intent.UPDATE_STATE);
createResponse
Constructs a successful RPC response object, used to reply to a received request.
Parameters
- requestId:
RequestID - method:
string - data:
D (unknown) - timestamp:
Timestamp - appId:
AccountID - intent:
Intent
Returns:NitroliteRPCResponse<D>
Example
const response = NitroliteRPC.createResponse(1, "get_config", { version: "1.0" }, Date.now());
createErrorResponse
Constructs an RPC error response object, used to indicate a failure in processing a request.
Parameters
- requestId:
RequestID - method:
string - error:
RPCError - timestamp:
Timestamp - appId:
AccountID
Returns:NitroliteRPCResponse<null>
Example
const errorResponse = NitroliteRPC.createErrorResponse(1, "get_config", { code: -32601, message: "Method not found" }, Date.now());
Message Signing
signRequestMessage
Signs an RPC request message using the provided signer function, adding a signature to the request object.
Parameters
- request:
NitroliteRPCRequest<T> - signer:
MessageSigner
Returns:Promise<SignedNitroliteRPCRequest<T>>
Example
// Assuming 'request' is a NitroliteRPCRequest and 'signer' is a MessageSigner
const signedRequest = await NitroliteRPC.signRequestMessage(request, signer);
signResponseMessage
Signs an RPC response message. This is used in specific scenarios where responses also require authentication.
Parameters
- response:
NitroliteRPCResponse<D> - signer:
MessageSigner
Returns:Promise<SignedNitroliteRPCResponse<D>>
Example
// Assuming 'response' is a NitroliteRPCResponse and 'signer' is a MessageSigner
const signedResponse = await NitroliteRPC.signResponseMessage(response, signer);
Message Parsing & Validation
parseResponse
Parses and validates an incoming RPC response string or object, ensuring it conforms to the NitroliteRPC structure.
Parameters
- message:
string | object
Returns:ParsedResponse<D, E>
Example
try {
const parsed = NitroliteRPC.parseResponse(incomingMessageString);
if (parsed.success) {
// process parsed.result
} else {
// process parsed.error
}
} catch (e) {
// handle malformed message
}
These methods ensure that all communication adheres to the defined RPC structure and security requirements.
Generic Message Structure
The NitroliteRPC class operates on messages adhering to the following general structures. For precise details on each field and for specific message types, please refer to the RPC Type Definitions.
// Generic Request message structure
{
"req": [requestId, method, params, timestamp], // Core request tuple
"int"?: Intent, // Optional intent for state changes
"acc"?: AccountID, // Optional account scope (channel/app ID)
"sig": [signature] // Array of signatures
}
// Generic Response message structure
{
"res": [requestId, method, dataPayload, timestamp], // Core response tuple
"acc"?: AccountID, // Optional account scope
"int"?: Intent, // Optional intent
"sig"?: [signature] // Optional signatures for certain response types
}
Next Steps
Dive deeper into the specifics of the RPC system: