Skip to content

P2P RPC Protocol Specification

This document defines the JSON-based Remote Procedure Call (RPC) protocol used for secure communication over the ToolBoxV2 P2P network.

Overview

The protocol is designed to be simple, extensible, and secure. All messages are JSON objects, which are then serialized into a string, encoded to UTF-8 bytes, and then E2E encrypted by the tcm peer before being sent over the P2P data channel.

Message Structure

There are two main types of messages: Request and Response.

Request Message

A message sent from a Consumer to a Provider to execute a function.

{
  "type": "request",
  "call_id": "unique-string-identifier-123",
  "module": "MyModule",
  "function": "my_function_name",
  "args": ["positional_arg1", 42],
  "kwargs": {
    "keyword_arg1": "value1",
    "optional_arg": true
  }
}

Fields:

  • type (string, required): Must be "request".
  • call_id (string, required): A unique identifier (e.g., a UUID) generated by the Consumer. This ID is used to correlate a Response with its original Request.
  • module (string, required): The name of the ToolBoxV2 module to be called (e.g., "CloudM").
  • function (string, required): The name of the function to execute within the specified module.
  • args (array, optional): A list of positional arguments for the function. Defaults to [] if not provided.
  • kwargs (object, optional): A dictionary of keyword arguments for the function. Defaults to {} if not provided.

Response Message

A message sent from a Provider back to the Consumer after a function has been executed.

Success Response

{
  "type": "response",
  "call_id": "unique-string-identifier-123",
  "result": {
    "status": "ok",
    "data": { "some_key": "some_value" }
  },
  "error": null
}

Error Response

{
  "type": "response",
  "call_id": "unique-string-identifier-123",
  "result": null,
  "error": {
    "code": 500,
    "message": "An internal error occurred.",
    "details": "Traceback..."
  }
}

Fields:

  • type (string, required): Must be "response".
  • call_id (string, required): The call_id from the original Request message.
  • result (any, nullable): The data returned by the successful execution of the function. This should be JSON-serializable. It is null if an error occurred.
  • error (object, nullable): An object describing the error if the function execution failed. It is null on success.
    • code (integer): An error code (e.g., 403 for Forbidden, 404 for Not Found, 500 for Internal Server Error).
    • message (string): A human-readable error message.
    • details (string, optional): Additional details, such as a traceback.