PoC for PVM JSON-RPC websockets interface ready to be connected to the PVM debugger

The idea is to expose PVM methods through the Websockets on a given port to allow PVM debugger to connect to it and control the PVM from the outside.

Running the app

npm i
node index.js

The communication protocol

The communication that PVM debugger is initializing adheres to the JSON RPC 2.0: https://www.jsonrpc.org/specification

Flow of communication

• PVM debugger starts with load method
• As it receives that the PVM was successfully started it now starts 3 more methods to initialize it:
  • getPageDump
  • resetGenericWithMemory
  • getRegisters
• then the nextStep is called directly afterwards with following methods to get the result after the next step:
  • getProgramCounter
  • getGasLeft
  • getStatus
  • getPageDump
  • getRegisters

API

The WebSocket server runs on ws://localhost:8765 and implements the JSON-RPC 2.0 protocol. Below are the supported methods:

load

Loads the WebAssembly PVM instance.

{
  "jsonrpc": "2.0",
  "method": "load",
  "params": [],  // No parameters required
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "result": "load",
  "id": 1
}

getPageDump

Retrieves the current page dump from the PVM.

{
  "jsonrpc": "2.0",
  "method": "getPageDump",
  "params": [
    0  // Optional: page index (number)
  ],
  "id": 2
}

Response:

{
  "jsonrpc": "2.0",
  "result": [0, 1, 2, 3, ...],  // Array of numbers (converted from Uint8Array)
  "id": 2,
  "method": "getPageDump"
}

getRegisters

Retrieves the current register values from the PVM.

{
  "jsonrpc": "2.0",
  "method": "getRegisters",
  "params": [],  // No parameters required
  "id": 3
}

Response:

{
  "jsonrpc": "2.0",
  "result": [0, 1, 2, 3, ...],  // Array of numbers (converted from Uint8Array)
  "id": 3,
  "method": "getRegisters"
}

resetGenericWithMemory

Resets the PVM with specified memory configuration.

{
  "jsonrpc": "2.0",
  "method": "resetGenericWithMemory",
  "params": [
    [/* program bytes */],     // Array of numbers (will be converted to Uint8Array)
    [/* register bytes */],    // Array of numbers (will be converted to Uint8Array)
    [/* page_map bytes */],    // Array of numbers (will be converted to Uint8Array)
    [/* chunks bytes */],      // Array of numbers (will be converted to Uint8Array)
    "1000000"                  // Gas limit as string (will be converted to BigInt)
  ],
  "id": 4
}

Response:

{
  "jsonrpc": "2.0",
  "result": undefined,  // The operation doesn't return a specific value
  "id": 4
}

setGasLeft

Sets the remaining gas in the PVM.

{
  "jsonrpc": "2.0",
  "method": "setGasLeft",
  "params": [
    "1000000"  // Gas amount as string (will be converted to BigInt)
  ],
  "id": 5
}

Response:

{
  "jsonrpc": "2.0",
  "result": undefined,  // The operation doesn't return a specific value
  "id": 5
}

nextStep

Executes the next step in the PVM.

{
  "jsonrpc": "2.0",
  "method": "nextStep",
  "params": [],  // No parameters required
  "id": 6
}

Response:

{
  "jsonrpc": "2.0",
  "result": true,  // Boolean indicating whether execution can continue
  "id": 6
}

nSteps

Executes multiple steps in the PVM.

{
  "jsonrpc": "2.0",
  "method": "nSteps",
  "params": [
    10  // Number of steps to execute (number)
  ],
  "id": 7
}

Response:

{
  "jsonrpc": "2.0",
  "result": true,  // Boolean indicating whether execution can continue
  "id": 7
}

getProgramCounter

Gets the current program counter value.

{
  "jsonrpc": "2.0",
  "method": "getProgramCounter",
  "params": [],  // No parameters required
  "id": 8
}

Response:

{
  "jsonrpc": "2.0",
  "result": 42,  // Number representing the current program counter
  "id": 8
}

setNextProgramCounter

Sets the next program counter value.

{
  "jsonrpc": "2.0",
  "method": "setNextProgramCounter",
  "params": [
    100  // New program counter value (number)
  ],
  "id": 9
}

Response:

{
  "jsonrpc": "2.0",
  "result": undefined,  // The operation doesn't return a specific value
  "id": 9
}

getStatus

Gets the current status of the PVM.

{
  "jsonrpc": "2.0",
  "method": "getStatus",
  "params": [],  // No parameters required
  "id": 10
}

Response:

{
  "jsonrpc": "2.0",
  "result": 255,  // Number representing the status code
  "id": 10
}

Status code values:

• 255: Ok
• 0: Halt
• 1: Panic
• 2: Fault
• 3: Host
• 4: OutOfGas

getExitArg

Gets the exit argument from the PVM.

{
  "jsonrpc": "2.0",
  "method": "getExitArg",
  "params": [],  // No parameters required
  "id": 11
}

Response:

{
  "jsonrpc": "2.0",
  "result": 0,  // Number representing the exit argument
  "id": 11
}

getGasLeft

Gets the remaining gas in the PVM.

{
  "jsonrpc": "2.0",
  "method": "getGasLeft",
  "params": [],  // No parameters required
  "id": 12
}

Response:

{
  "jsonrpc": "2.0",
  "result": "999000",  // String representation of the remaining gas (BigInt)
  "id": 12
}

setRegisters

Sets register values in the PVM.

{
  "jsonrpc": "2.0",
  "method": "setRegisters",
  "params": [
    [/* register bytes */]  // Array of numbers (will be converted to Uint8Array)
  ],
  "id": 13
}

Response:

{
  "jsonrpc": "2.0",
  "result": undefined,  // The operation doesn't return a specific value
  "id": 13
}

setMemory

Sets memory values in the PVM.

{
  "jsonrpc": "2.0",
  "method": "setMemory",
  "params": [
    1000,                // Memory address (number)
    [/* memory bytes */]  // Array of numbers (will be converted to Uint8Array)
  ],
  "id": 14
}

Response:

{
  "jsonrpc": "2.0",
  "result": undefined,  // The operation doesn't return a specific value
  "id": 14
}

resetGeneric

Resets the PVM to a generic state.

{
  "jsonrpc": "2.0",
  "method": "resetGeneric",
  "params": [
    [/* program bytes */],   // Array of numbers (will be converted to Uint8Array)
    [/* register bytes */],  // Array of numbers (will be converted to Uint8Array)
    "1000000"                // Gas limit as string (will be converted to BigInt)
  ],
  "id": 15
}

Response:

{
  "jsonrpc": "2.0",
  "result": undefined,  // The operation doesn't return a specific value
  "id": 15
}

Response format

All responses follow the JSON-RPC 2.0 format:

{
  "jsonrpc": "2.0",
  "result": resultValue,
  "id": requestId
}

For methods like getPageDump and getRegisters, the result is converted from a typed array to a regular array before being sent.

Error responses

If an error occurs, the response will have this format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": errorCode,
    "message": "Error message"
  },
  "id": requestId
}

Common error codes:

• -32601: Method not found
• -32603: Internal error running WASM