KIP-0011 -- standardization and simplification of Stratum

kip-0011.md

@@ -0,0 +1,117 @@
+```
+  KIP: 11
+  Layer: Applications, PoW
+  Title: Simplified Stratum
+  Authors: KaffinPX <[email protected]>
+  Status: In-progress 
+```
+
+# Motivation
+
+This proposal introduces a simplified version of the Stratum protocol for mining pools in the Kaspa. The goal is to improve efficiency by transmitting less data and reducing complexity for developers.
+
+# Specification
+
+The Stratum protocol mostly adheres to the [JSON RPC 2.0](https://www.jsonrpc.org/specification) specification.
+
+Communication happens over a bidirectional channel of TCP with messages encoded as JSON with `LF` delimiter—in this document written as `\n`.
+
+Since requests can be processed in any order, each request should have an unique id. This allows for matching each request with its corresponding response. Responses must include the same id as the request they are replying to.
+
+If a request doesn't have a specific response and didn't fail, it should return `true`. Additionally, notifications sent by the server should not include an `id`.
+
+### Methods
+
+- [subscribe](#subscribe)
+- [authorize](#authorize)
+- [notify](#notify)
+- [submit](#submit)
+
+### Protocol flow
+
+The following shows what a session might look like from subscription to submitting a solution.
+
+```
+Client                                Server
+  |                                     |
+  | ----------- subscribe ------------> |
+  | ----------- authorize ------------> |
+  |                                     |
+  | <------------- notify ------------- |
+  |                                     |
+  | -------------- submit ------------> |
+```
+
+### Errors
+
+Whenever a call triggers an error, the response must include an `error` field which maps to a **list** of the following values:
+
+- [ `code`: an integer representing the error code ]
+- [ `message`: a string describing the error ]
+
+For example:
+
+```
+{"id": 10, "result": false, "error": [21, "Job not found"]}
+```
+
+Errors should be identified by their code, and applications should handle errors based on this code, not the message.
+In addition to the error codes defined in the JSON RPC 2.0 specification, the following error codes are available:
+
+- `20` - Other/Unknown
+- `21` - Header not found (stale)
+- `22` - Duplicate share
+- `23` - Low difficulty share
+- `24` - Unauthorized worker
+- `25` - Not subscribed
+
+The `message` field should be a brief description of the error for easy understanding.
+
+#### subscribe
+
+The subscribe method allows a client to indicate its interest in receiving job notifications with an address from the server. This method can include telemetry data about the miner's software.
+
+The address may be used by pools for authorization according to the guidelines specified in [KIP-05](https://github.com/kaspanet/kips/blob/master/kip-0005.md).
+Can be used multiple times for replacing the address(reauthorization).
+
+##### Request
+```
+{"id": 0, "method": "subscribe", "params": ["kaspa:qzmx4g9nueqwgk508yepvjumckfag7dd3sggl72k9q0uzt8h0nxs2608pk88p", "KaspaMiner/1.0.0"]}
+```
+
+#### authorize
+
+The authorize method is used by the client to authenticate its workers with the server, optionally using a worker name. Upon successful authorization, the server responds with an assigned ID, specialized nonce(2 bytes) and difficulty for the worker.
+
+##### Request
+```
+{"id": 1, "method": "authorize", "params": ["Miner1"]}
+```
+
+##### Response
+```
+{"id": 1, "result": [0, "000a", 8]}
+```
+
+#### notify
+
+The notify method is used by the server to send a new mining job to the client. This job includes the header hash of the block and a timestamp. May also include a difficulty if network conditions are changed.
+
+##### Request
+```
+{"method": "notify", "params": ["0", "8e42cac2061d8341f4147de0db16bfadbc66859e2b29bc01915eb60452f5ef97", "1716124061964", 8]}
+```
+
+#### submit
+
+The submit method allows the client to submit a completed job back to the server. The submission includes the worker ID, the block header hash and the solution (nonce). The server may respond with an updated difficulty for the worker.
+
+##### Request
+```
+{"method": "submit", "params": [0, "8e42cac2061d8341f4147de0db16bfadbc66859e2b29bc01915eb60452f5ef97", "2261662188495855071"]}
+```
+
+##### Response
+```
+{"id": 1, "result": 8}
+```