Detailed reference for functions that create specific, signed Nitrolite RPC request messages.

import MethodDetails from '@site/src/components/MethodDetails';

RPC Message Creation API

The functions detailed below are part of the @erc7824/nitrolite SDK and provide a convenient way to create fully formed, signed, and stringified JSON RPC request messages. These messages are ready for transmission over a WebSocket or any other transport layer communicating with a Nitrolite-compatible broker.

Each function typically takes a MessageSigner (a function you provide to sign messages, usually integrating with a user's wallet) and other relevant parameters, then returns a Promise<string> which resolves to the JSON string of the signed RPC message.

Authentication

These functions are used for the client authentication flow with the broker. The typical sequence is:

Client sends an auth_request (using createAuthRequestMessage).
Broker responds with an auth_challenge.
Client signs the challenge and sends an auth_verify (using createAuthVerifyMessageFromChallenge or createAuthVerifyMessage).
Broker responds with auth_success or auth_failure.

General & Keep-Alive

Functions for general RPC interactions like keep-alive messages.

Query Operations

Functions for retrieving information from the broker.

Application Session Management

Functions for creating and closing application sessions (state channels).

Application-Specific Messaging

Function for sending messages within an active application session.

Ledger Channel Management

Functions for managing the underlying ledger channels (direct channels with the broker).

Advanced: Creating a Local Signer for Development

To begin, you'll often need a fresh key pair (private key, public key, and address). The generateKeyPair utility can be used for this:

import { ethers } from "ethers"; // Make sure ethers is installed

// Definition (as provided in your example)
interface CryptoKeypair {
    privateKey: string;
    publicKey: string;
    address: string;
}

export const generateKeyPair = async (): Promise<CryptoKeypair> => {
    try {
        const wallet = ethers.Wallet.createRandom();
        const privateKeyHash = ethers.utils.keccak256(wallet.privateKey);
        const walletFromHashedKey = new ethers.Wallet(privateKeyHash);

        return {
            privateKey: privateKeyHash,
            publicKey: walletFromHashedKey.publicKey,
            address: walletFromHashedKey.address,
        };
    } catch (error) {
        console.error('Error generating keypair, using fallback:', error);
        const randomHex = ethers.utils.randomBytes(32);
        const privateKey = ethers.utils.keccak256(randomHex);
        const wallet = new ethers.Wallet(privateKey);

        return {
            privateKey: privateKey,
            publicKey: wallet.publicKey,
            address: wallet.address,
        };
    }
};

// Usage:
async function main() {
  const keyPair = await generateKeyPair();
  console.log("Generated Private Key:", keyPair.privateKey);
  console.log("Generated Address:", keyPair.address);
  // Store keyPair.privateKey securely if you need to reuse this signer
}

This function creates a new random wallet, hashes its private key for deriving a new one (a common pattern for deterministic key generation or added obfuscation, though the security implications depend on the exact use case), and returns the private key, public key, and address.

Creating a Signer from a Private Key

Once you have a private key (either generated as above or from a known development account), you can create a MessageSigner compatible with the RPC message creation functions. The MessageSigner interface typically expects an asynchronous sign method.

import { ethers } from "ethers";
import { Hex } from "viem"; // Assuming Hex type is from viem or similar

// Definitions (as provided in your example)
type RequestData = unknown; // Placeholder for actual request data type
type ResponsePayload = unknown; // Placeholder for actual response payload type

interface WalletSigner {
    publicKey: string;
    address: Hex;
    sign: (payload: RequestData | ResponsePayload) => Promise<Hex>;
}

export const createEthersSigner = (privateKey: string): WalletSigner => {
    try {
        const wallet = new ethers.Wallet(privateKey);

        return {
            publicKey: wallet.publicKey,
            address: wallet.address as Hex,
            sign: async (payload: RequestData | ResponsePayload): Promise<Hex> => {
                try {
                    // The NitroliteRPC.hashMessage method should ideally be used here
                    // to ensure the exact same hashing logic as the SDK internals.
                    // For demonstration, using a generic hashing approach:
                    const messageToSign = JSON.stringify(payload);
                    const messageHash = ethers.utils.id(messageToSign); // ethers.utils.id performs keccak256
                    const messageBytes = ethers.utils.arrayify(messageHash);

                    const flatSignature = await wallet._signingKey().signDigest(messageBytes);
                    const signature = ethers.utils.joinSignature(flatSignature);
                    return signature as Hex;
                } catch (error) {
                    console.error('Error signing message:', error);
                    throw error;
                }
            },
        };
    } catch (error) {
        console.error('Error creating ethers signer:', error);
        throw error;
    }
};

// Usage:
async function setupSigner() {
  const keyPair = await generateKeyPair(); // Or use a known private key
  const localSigner = createEthersSigner(keyPair.privateKey);

  // Now 'localSigner' can be passed to the RPC message creation functions:
  // const authRequest = await createAuthRequestMessage(localSigner.sign, localSigner.address as Address);
  // console.log("Auth Request with local signer:", authRequest);
}

Important Considerations for createEthersSigner:

Hashing Consistency: The sign method within createEthersSigner must hash the payload in a way that is identical to how the NitroliteRPC class (specifically NitroliteRPC.hashMessage) expects messages to be hashed before signing. The example above uses ethers.utils.id(JSON.stringify(payload)). It's crucial to verify if the SDK's internal hashing uses a specific message prefix (e.g., EIP-191 personal_sign prefix) or a different serialization method. If the SDK does not use a standard EIP-191 prefix, or uses a custom one, your local signer's hashing logic must replicate this exactly for signatures to be valid. Using NitroliteRPC.hashMessage(payload) directly (if payload matches the NitroliteRPCMessage structure) is the safest way to ensure consistency.
Type Compatibility: Ensure the Address type expected by functions like createAuthRequestMessage is compatible with localSigner.address. The example uses localSigner.address as Address assuming Address is 0x${string}.
Error Handling: The provided examples include basic error logging. Robust applications should implement more sophisticated error handling.

RPC Message Creation API

On this page