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.

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

<MethodDetails name="createRequest" description="Constructs a standard RPC request object, forming the base structure for any request sent via the NitroliteRPC protocol." params={[ { name: "requestId", type: "RequestID", description: "A unique identifier for the request." }, { name: "method", type: "string", description: "The RPC method name." }, { name: "params", type: "T (unknown[])", description: "An array of parameters for the RPC method." }, { name: "timestamp", type: "Timestamp", description: "The current timestamp in milliseconds." } ]} returns="NitroliteRPCRequest" example={const request = NitroliteRPC.createRequest(1, "get_config", [], Date.now());} />

<MethodDetails name="createAppRequest" description="Constructs an RPC request object specifically scoped to an application, including application ID and optional intent." params={[ { name: "requestId", type: "RequestID", description: "A unique identifier for the request." }, { name: "method", type: "string", description: "The RPC method name." }, { name: "params", type: "T (unknown[])", description: "An array of parameters for the RPC method." }, { name: "timestamp", type: "Timestamp", description: "The current timestamp in milliseconds." }, { name: "appId", type: "AccountID", description: "The identifier of the target application or channel." }, { name: "intent", type: "Intent", description: "Optional intent associated with the application request.", optional: true } ]} returns="NitroliteRPCRequest" example={const appRequest = NitroliteRPC.createAppRequest(1, "app_update", [{data: "0x123"}], Date.now(), "app_0xabc", Intent.UPDATE_STATE);} />

<MethodDetails name="createResponse" description="Constructs a successful RPC response object, used to reply to a received request." params={[ { name: "requestId", type: "RequestID", description: "The ID of the request this response corresponds to." }, { name: "method", type: "string", description: "The original RPC method name." }, { name: "data", type: "D (unknown)", description: "The payload/data of the response." }, { name: "timestamp", type: "Timestamp", description: "The current timestamp in milliseconds." }, { name: "appId", type: "AccountID", description: "Optional application/channel scope.", optional: true }, { name: "intent", type: "Intent", description: "Optional intent associated with the response.", optional: true } ]} returns="NitroliteRPCResponse" example={const response = NitroliteRPC.createResponse(1, "get_config", { version: "1.0" }, Date.now());} />

<MethodDetails name="createErrorResponse" description="Constructs an RPC error response object, used to indicate a failure in processing a request." params={[ { name: "requestId", type: "RequestID", description: "The ID of the request this error response corresponds to." }, { name: "method", type: "string", description: "The original RPC method name." }, { name: "error", type: "RPCError", description: "An error object detailing the failure." }, { name: "timestamp", type: "Timestamp", description: "The current timestamp in milliseconds." }, { name: "appId", type: "AccountID", description: "Optional application/channel scope.", optional: true } ]} returns="NitroliteRPCResponse" example={const errorResponse = NitroliteRPC.createErrorResponse(1, "get_config", { code: -32601, message: "Method not found" }, Date.now());} />

Message Signing

<MethodDetails name="signRequestMessage" description="Signs an RPC request message using the provided signer function, adding a signature to the request object." params={[ { name: "request", type: "NitroliteRPCRequest", description: "The RPC request object to sign." }, { name: "signer", type: "MessageSigner", description: "An async function that takes a message string and returns a Promise (signature)." } ]} returns="Promise<SignedNitroliteRPCRequest>" example={// Assuming 'request' is a NitroliteRPCRequest and 'signer' is a MessageSigner const signedRequest = await NitroliteRPC.signRequestMessage(request, signer);} />

<MethodDetails name="signResponseMessage" description="Signs an RPC response message. This is used in specific scenarios where responses also require authentication." params={[ { name: "response", type: "NitroliteRPCResponse", description: "The RPC response object to sign." }, { name: "signer", type: "MessageSigner", description: "An async function that takes a message string and returns a Promise (signature)." } ]} returns="Promise<SignedNitroliteRPCResponse>" example={// Assuming 'response' is a NitroliteRPCResponse and 'signer' is a MessageSigner const signedResponse = await NitroliteRPC.signResponseMessage(response, signer);} />

Message Parsing & Validation

<MethodDetails name="parseResponse" description="Parses and validates an incoming RPC response string or object, ensuring it conforms to the NitroliteRPC structure." params={[ { name: "message", type: "string | object", description: "The raw RPC response message (JSON string or pre-parsed 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: