diff --git a/spec/README.md b/spec/README.md index c7f83ca753..69c0f2fd5f 100644 --- a/spec/README.md +++ b/spec/README.md @@ -22,4 +22,5 @@ CodeChain is a programmable blockchain supporting multiple asset types. You can * [Merkle Trie](Merkle-Trie.md) * [Digital Signature](Digital-Signature.md) * [JSON RPC](JSON-RPC.md) +* [Stratum](Stratum.md) diff --git a/spec/Stratum.md b/spec/Stratum.md new file mode 100644 index 0000000000..146d879f2f --- /dev/null +++ b/spec/Stratum.md @@ -0,0 +1,144 @@ +Stratum is a light-weight mining protocol. + +# CLI options for Stratum + + * `--no-stratum` + > Do not run stratum. + * `--stratum-port ` + > Listen for stratum connections on PORT. [default: 8008] + +# List of methods + + * [mining.subscribe](#mining.subscribe) + * [mining.authorize](#mining.authorize) + * [mining.notify](#mining.notify) + * [mining.submit](#mining.submit) + +# Specification + +## mining.subscribe + +Used for subscribing mining jobs. + +Params: No parameters + +Return Type: No parameters + +Request Example +``` +{ + "jsonrpc": "2.0", + "id": 1, + "method": "mining.subscribe", + "params": [] +} +``` + +Response Example +``` +{ + "jsonrpc": "2.0", + "id": 1, + "result": [], + "error": null +} +``` + +## mining.authorize + +Used for authorizing miners. + +Params: + 1. name: `string` + 2. password: `string` + +Return Type: `bool` + +Request Example +``` +{ + "jsonrpc": "2.0", + "id":2, + "method": "mining.authorize", + "params": ["miner1", "password"] +} +``` + +Response Example +``` +{ + "jsonrpc": "2.0", + "id": 2, + "result": true, + "error": null +} +``` + +## mining.notify + +Used for sending notifications regarding mining jobs. + +Params: `Work` + +Notification Example +``` +{ + "jsonrpc": "2.0", + "id": 3, + "method": "mining.notify", + "params": { + "0x56642f04d519ae3262c7ba6facf1c5b11450ebaeb7955337cfbc45420d573077", + "100" + }, +} +``` + +## mining.submit + +Used for submitting a proof-of-work solution. + +Params: + 1. powHash: `string` + 2. seal: `string[]` + +Return Type: `bool` + +Request Example +``` +{ + "jsonrpc": "2.0", + "id": 4, + "method": "mining.submit", + "params": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", ["0x56642f04d519ae3262c7ba6facf1c5b11450ebaeb7955337cfbc45420d573077"]], +} +``` + +Response Example +``` +{ + "jsonrpc": "2.0", + "id": 4, + "result": true, + "error": null +} +``` + +## Exception Handling (DRAFT) +Stratum defines simple exception handling. Example of a rejected share looks like: +``` +{ + "jsonrpc": "2.0", + "id": 5, + "result": null, + "error": (21, "Job not found", null) +} +``` + +Where the error field is defined as (error_code, human_readable_message, traceback). Traceback may contain additional information about debugging errors. +Proposed error codes for mining services are: +* 20 - Other/Unknown +* 21 - Job not found (=stale) +* 22 - Duplicate share +* 23 - Low target share +* 24 - Unauthorized worker +* 25 - Not subscribed