JSON-RPC
JSON-RPC is a lightweight remote procedure call (RPC) protocol that uses JSON (JavaScript Object Notation) as its data format. In Bitcoin mining, it serves as the message encoding format used by the Stratum protocol for communication between mining hardware and pool servers.
Understanding JSON-RPC
Section titled “Understanding JSON-RPC”Remote Procedure Call (RPC) is a concept where one computer tells another computer to execute a specific function and return the result. JSON-RPC standardizes how these requests and responses are formatted using JSON, a human-readable text format based on key-value pairs.
Think of JSON-RPC as a standardized form for ordering at a restaurant. Instead of shouting your order in free-form (which might be misunderstood), you fill out a structured order slip with specific fields: your table number, the dish name, any modifications, and a request ID. The kitchen fills out a matching response slip with your request ID and either the dish or an error message. Everyone knows exactly where to look for each piece of information.
Every JSON-RPC message in the Stratum protocol follows a standard structure:
Request:
{"id": 1, "method": "mining.subscribe", "params": []}Response:
{"id": 1, "result": [...], "error": null}Notification (no ID, no response expected):
{"id": null, "method": "mining.notify", "params": [...]}The id field links requests to responses. The method field specifies what action to perform. The params array carries the data. The result or error field in the response carries the outcome.
Practical Example
Section titled “Practical Example”When an ASIC miner submits a share, it sends a JSON-RPC message like:
{"id": 4, "method": "mining.submit", "params": ["worker1", "job_id", "extranonce2", "ntime", "nonce"]}The pool processes the share and responds:
{"id": 4, "result": true, "error": null}A result of true means the share was accepted. If the share was invalid, result would be false and the error field would contain details about why it was rejected.