From c9a24834200379831f496d289c40a9ad6a64dc56 Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Mon, 20 May 2024 19:54:44 +0300 Subject: [PATCH 1/8] Add KIP prototype --- kip-0010.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 kip-0010.md diff --git a/kip-0010.md b/kip-0010.md new file mode 100644 index 0000000..90f5694 --- /dev/null +++ b/kip-0010.md @@ -0,0 +1,123 @@ +``` +  KIP: 10 +  Layer: Applications, PoW +  Title: Simplified Stratum +  Authors: KaffinPX +  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) +- [setDifficulty](#setDifficulty) +- [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 ------------> | + | <-------- setDifficulty ----------- | + | | + | <------------- 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 and specialized nonce for the worker. + +##### Request +``` +{"id": 1, "method": "authorize", "params": ["Miner1"]} +``` + +##### Response +``` +{"id": 1, "result": [0, "0000000a"]} +``` + +#### setDifficulty + +The setDifficulty method is used by the server to notify the client of the target difficulty for the mining job. The difficulty level dictates how challenging it is to find a valid block hash. + +##### Request +``` +{"method": "setDifficulty", "params": [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. + +##### Request +``` +{"method": "notify", "params": ["0", "8e42cac2061d8341f4147de0db16bfadbc66859e2b29bc01915eb60452f5ef97", "1716124061964"]} +``` + +#### 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). + +##### Request +``` +{"method": "submit", "params": [0, "8e42cac2061d8341f4147de0db16bfadbc66859e2b29bc01915eb60452f5ef97", "2261662188495855071"]} +``` From ca62bc525a401a80404ef4299c685d8cf66bdb9c Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Wed, 22 May 2024 20:19:13 +0300 Subject: [PATCH 2/8] Update kip-0010.md --- kip-0010.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/kip-0010.md b/kip-0010.md index 90f5694..5a60847 100644 --- a/kip-0010.md +++ b/kip-0010.md @@ -46,7 +46,7 @@ Client Server ### Errors -Whenever a call triggers an error, the response MUST include an `error` field which maps to a **list** of the following values: +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 ] @@ -61,7 +61,7 @@ Errors should be identified by their code, and applications should handle errors 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) +- `21` - Header not found (stale) - `22` - Duplicate share - `23` - Low difficulty share - `24` - Unauthorized worker From ba708cb42ba0c627c5b8cb1fad59da2d7bc39c50 Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Fri, 24 May 2024 00:25:46 +0300 Subject: [PATCH 3/8] setDifficulty optional parameter for worker targeting --- kip-0010.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/kip-0010.md b/kip-0010.md index 5a60847..0c7733d 100644 --- a/kip-0010.md +++ b/kip-0010.md @@ -99,9 +99,11 @@ The authorize method is used by the client to authenticate its workers with the The setDifficulty method is used by the server to notify the client of the target difficulty for the mining job. The difficulty level dictates how challenging it is to find a valid block hash. +Optionally it can include a worker id to target a specific worker for change. + ##### Request ``` -{"method": "setDifficulty", "params": [8]} +{"method": "setDifficulty", "params": [8, 0]} ``` #### notify From 885c18d15f461d05f2b71d37b85dfe687251d43d Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Fri, 24 May 2024 01:11:57 +0300 Subject: [PATCH 4/8] Remove setDifficulty and move its parts into notify and submit --- kip-0010.md | 24 ++++++++---------------- 1 file changed, 8 insertions(+), 16 deletions(-) diff --git a/kip-0010.md b/kip-0010.md index 0c7733d..e3fa2d4 100644 --- a/kip-0010.md +++ b/kip-0010.md @@ -24,7 +24,6 @@ If a request doesn't have a specific response and didn't fail, it should return - [subscribe](#subscribe) - [authorize](#authorize) -- [setDifficulty](#setDifficulty) - [notify](#notify) - [submit](#submit) @@ -37,7 +36,6 @@ Client Server | | | ----------- subscribe ------------> | | ----------- authorize ------------> | - | <-------- setDifficulty ----------- | | | | <------------- notify ------------- | | | @@ -95,31 +93,25 @@ The authorize method is used by the client to authenticate its workers with the {"id": 1, "result": [0, "0000000a"]} ``` -#### setDifficulty - -The setDifficulty method is used by the server to notify the client of the target difficulty for the mining job. The difficulty level dictates how challenging it is to find a valid block hash. - -Optionally it can include a worker id to target a specific worker for change. - -##### Request -``` -{"method": "setDifficulty", "params": [8, 0]} -``` - #### 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. +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 target difficulty if network conditions are changed. ##### Request ``` -{"method": "notify", "params": ["0", "8e42cac2061d8341f4147de0db16bfadbc66859e2b29bc01915eb60452f5ef97", "1716124061964"]} +{"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 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 if network conditions are changed. ##### Request ``` {"method": "submit", "params": [0, "8e42cac2061d8341f4147de0db16bfadbc66859e2b29bc01915eb60452f5ef97", "2261662188495855071"]} ``` + +##### Response +``` +{"id": 1, "result": 8} +``` From 719c0190da63203032a55af3bd198d638977554d Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Fri, 24 May 2024 01:37:45 +0300 Subject: [PATCH 5/8] Return initial difficulty on authorize calls --- kip-0010.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/kip-0010.md b/kip-0010.md index e3fa2d4..b13aae0 100644 --- a/kip-0010.md +++ b/kip-0010.md @@ -81,7 +81,7 @@ Can be used multiple times for replacing the address(reauthorization). #### 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 and specialized nonce for the worker. +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 and difficulty for the worker. ##### Request ``` @@ -90,12 +90,12 @@ The authorize method is used by the client to authenticate its workers with the ##### Response ``` -{"id": 1, "result": [0, "0000000a"]} +{"id": 1, "result": [0, "0000000a", 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 target difficulty if network conditions are changed. +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 ``` @@ -104,7 +104,7 @@ The notify method is used by the server to send a new mining job to the client. #### 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 if network conditions are changed. +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 ``` From 50e377a6ed6702e2624cdec233edf169e197ddc0 Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Mon, 27 May 2024 17:32:55 +0300 Subject: [PATCH 6/8] 3 bytes extra nonce --- kip-0010.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/kip-0010.md b/kip-0010.md index b13aae0..18417d6 100644 --- a/kip-0010.md +++ b/kip-0010.md @@ -90,7 +90,7 @@ The authorize method is used by the client to authenticate its workers with the ##### Response ``` -{"id": 1, "result": [0, "0000000a", 8]} +{"id": 1, "result": [0, "00000a", 8]} ``` #### notify From dae871f3d07914f77c346cbfedb0ac2286666f17 Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Fri, 31 May 2024 03:00:57 +0300 Subject: [PATCH 7/8] Apply IceRivers suggestion --- kip-0010.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/kip-0010.md b/kip-0010.md index 18417d6..98edfa4 100644 --- a/kip-0010.md +++ b/kip-0010.md @@ -81,7 +81,7 @@ Can be used multiple times for replacing the address(reauthorization). #### 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 and difficulty for the worker. +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 ``` @@ -90,7 +90,7 @@ The authorize method is used by the client to authenticate its workers with the ##### Response ``` -{"id": 1, "result": [0, "00000a", 8]} +{"id": 1, "result": [0, "000a", 8]} ``` #### notify From 36e92365ce6b4b7e6220b0a432fcbed3b5871ef4 Mon Sep 17 00:00:00 2001 From: KaffinPX <73744616+KaffinPX@users.noreply.github.com> Date: Sun, 16 Jun 2024 17:01:41 +0300 Subject: [PATCH 8/8] 10 => 11 --- kip-0010.md => kip-0011.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename kip-0010.md => kip-0011.md (99%) diff --git a/kip-0010.md b/kip-0011.md similarity index 99% rename from kip-0010.md rename to kip-0011.md index 98edfa4..d194fb8 100644 --- a/kip-0010.md +++ b/kip-0011.md @@ -1,5 +1,5 @@ ``` -  KIP: 10 +  KIP: 11   Layer: Applications, PoW   Title: Simplified Stratum   Authors: KaffinPX