grin/doc/stratum_KR.md

# Grin Stratum RPC 프로토콜

이 문서는 Grin에 구현되어 있는 현재 Stratum RPC protocol 을 설명한 것입니다.

## 목차

1. [Messages](#메세지_들)
    1. [getjobtemplate](#getjobtemplate)
    2. [job](#job)
    3. [keepalive](#keepalive)
    4. [login](#login)
    5. [status](#status)
    6. [submit](#submit)
2. [에러 메시지들](#error-messages)
3. [채굴자의 행동양식](#miner-behavior)
4. [참고 구현체](#reference-implementation)

## 메세지 들

이 섹션에서는 각 메시지와 그 응답에 대해서 상술합니다.
어느때든, 채굴자가 로그인을 제외한 다음 중 한 요청을 하고 login 이 요구된다면 채굴자는 다음과 같은 에러 메시지를 받게 됩니다.

| Field         | Content                                 |
| :------------ | :-------------------------------------- |
| id            | 요청 ID                                 |
| jsonrpc       | "2.0"                                   |
| method        | 채굴자가 보낸 method                        |
| error         | {"code":-32500,"message":"login first"} |

예시:

```JSON
{  
   "id":"10",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "error":{  
      "code":-32500,
      "message":"login first"
   }
}
```
만약에 요청이 다음중 하나가 아니라면, Stratum 서버가 아래와 같은 에러 메시지를 보내게 됩니다.

| Field         | Content                                      |
| :------------ | :------------------------------------------- |
| id            | 요청 ID                                       |
| jsonrpc       | "2.0"                                        |
| method        | 채굴자가 보낸 method                            |
| error         | {"code":-32601,"message":"Method not found"} |

예시:

```JSON
{  
   "id":"10",
   "jsonrpc":"2.0",
   "method":"getgrins",
   "error":{  
      "code":-32601,
      "message":"Method not found"
   }
}
```

### `getjobtemplate`

채굴자에 의해 시작되는 메시지입니다.
채굴자는 이 메시지로 작업을 요청 할 수 있습니다.

#### Request

| Field         | Content                        |
| :------------ | :----------------------------- |
| id            | 요청 ID                         |
| jsonrpc       | "2.0"                          |
| method        | "getjobtemplate"               |
| params        | null                           |

예시 :

``` JSON
{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "params":null
}
```

#### Response

Response 는 두가지 타입이 될 수 있습니다.

##### OK response

예시

``` JSON
{  
   "id":"0",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "result":{  
      "difficulty":1,
      "height":13726,
      "job_id":4,
      "pre_pow":"00010000000000003c4d0171369781424b39c81eb39de10cdf4a7cc27bbc6769203c7c9bc02cc6a1dfc6000000005b50f8210000000000395f123c6856055aab2369fe325c3d709b129dee5c96f2db60cdbc0dc123a80cb0b89e883ae2614f8dbd169888a95c0513b1ac7e069de82e5d479cf838281f7838b4bf75ea7c9222a1ad7406a4cab29af4e018c402f70dc8e9ef3d085169391c78741c656ec0f11f62d41b463c82737970afaa431c5cabb9b759cdfa52d761ac451276084366d1ba9efff2db9ed07eec1bcd8da352b32227f452dfa987ad249f689d9780000000000000b9e00000000000009954"
   }
}
```

##### Error response

만약 노드가 동기화 중이라면, 다음과 같은 메시지를 보낼것입니다.

| Field         | Content                                                   |
| :------------ | :-------------------------------------------------------- |
| id            | 요청 ID                                                    |
| jsonrpc       | "2.0"                                                     |
| method        | "getjobtemplate"                                          |
| error         | {"code":-32701,"message":"Node is syncing - Please wait"} |

예시:

```JSON
{  
   "id":"10",
   "jsonrpc":"2.0",
   "method":"getjobtemplate",
   "error":{  
      "code":-32000,
      "message":"Node is syncing - Please wait"
   }
}
```

### `job`

Stratum 서버로 인해 시작되는 메세지입니다.
Stratum 서버는 연결된 채굴자에게 작업을 자동적으로 보냅니다.
채굴자는 job_id=0 이면 현재의 작업을 중단해야 합니다. 그리고 현재의 작업을 현재 graph 가 완료되면 이 작업으로 대체해야 합니다.

#### Request

| Field         | Content                                                                   |
| :------------ | :------------------------------------------------------------------------- |
| id            | 요청 ID                                                                    |
| jsonrpc       | "2.0"                                                                     |
| method        | "job"                                                                     |
| params        | Int `difficulty`, `height`, `job_id` and string `pre_pow` |

예시:

``` JSON
{  
   "id":"Stratum",
   "jsonrpc":"2.0",
   "method":"job",
   "params":{  
      "difficulty":1,
      "height":16375,
      "job_id":5,
      "pre_pow":"00010000000000003ff723bc8c987b0c594794a0487e52260c5343288749c7e288de95a80afa558c5fb8000000005b51f15f00000000003cadef6a45edf92d2520bf45cbd4f36b5ef283c53d8266bbe9aa1b8daaa1458ce5578fcb0978b3995dd00e3bfc5a9277190bb9407a30d66aec26ff55a2b50214b22cdc1f3894f27374f568b2fe94d857b6b3808124888dd5eff7e8de7e451ac805a4ebd6551fa7a529a1b9f35f761719ed41bfef6ab081defc45a64a374dfd8321feac083741f29207b044071d93904986fa322df610e210c543c2f95522c9bdaef5f598000000000000c184000000000000a0cf"
   }
}
```

#### Response

이 메세지에는 Response 가 필요하지 않습니다.

### `keepalive`

연결을 계속 하기 위해서 채굴자에 의해 초기화 되는 메시지입니다.

#### Request

| Field         | Content                |
| :------------ | :--------------------- |
| id            | 요청 ID                 |
| jsonrpc       | "2.0"                  |
| method        | "keepalive"            |
| params        | null                   |

예시:

``` JSON
{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"keepalive",
   "params":null
}
```

#### Response

| Field         | Content                        |
| :------------ | :----------------------------- |
| id            | 요청 ID                         |
| jsonrpc       | "2.0"                          |
| method        | "keepalive"                    |
| result        | "ok"                           |
| error         | null                           |

예시:

``` JSON
{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"keepalive",
   "result":"ok",
   "error":null
}
```

### `login`

***
채굴자에 의해 시작되는 메시지입니다.
채굴자는 보통 채굴 프로그램으로 고정적으로 정해지는 login, password, agent 로 Grin Stratum 서버에 로그인 할 수 있습니다.

#### Request

| Field         | Content                        |
| :------------ | :----------------------------- |
| id            | 요청 ID                         |
| jsonrpc       | "2.0"                          |
| method        | "login"                        |
| params        | Strings: login, pass and agent |

예시:

``` JSON

{  
   "id":"0",
   "jsonrpc":"2.0",
   "method":"login",
   "params":{  
      "login":"login",
      "pass":"password",
      "agent":"grin-miner"
   }
}

```

#### Response

Response 는 두가지 타입이 될 수 있습니다.

##### OK response

| Field         | Content                        |
| :------------ | :----------------------------- |
| id            | 요청 ID                         |
| jsonrpc       | "2.0"                          |
| method        | "login"                        |
| result        | "ok"                           |
| error         | null                           |

예사:

``` JSON
{  
   "id":"1",
   "jsonrpc":"2.0",
   "method":"login",
   "result":"ok",
   "error":null
}
```

##### Error response

아직 구현되지 않았습니다. login이 필요할때, -32500 "Login firtst" 라는 에러를 리턴합니다.

### `status`

채굴자에 의해 시작되는 메시지입니다.
이 메시지는 채굴자에게 현재의 워커와 네트워크의 상태를 얻을 수 있게 합니다.

#### Request

| Field         | Content                |
| :------------ | :--------------------- |
| id            | 요청 ID                 |
| jsonrpc       | "2.0"                  |
| method        | "status"               |
| params        | null                   |

예시:

``` JSON
{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"status",
   "params":null
}
```

#### Response

Response 는 아래와 같습니다.

| Field         | Content                                                                                                  |
| :------------ | :------------------------------------------------------------------------------------------------------- |
| id            | 요청 ID                                                                                                   |
| jsonrpc       | "2.0"                                                                                                    |
| method        | "status"                                                                                                 |
| result        | String `id`. Integers `height`, `difficulty`, `accepted`, `rejected` and `stale`                         |
| error         | null                                                                                                     |

예시:

```JSON
{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"status",
   "result":{  
      "id":"5",
      "height":13726,
      "difficulty":1,
      "accepted":0,
      "rejected":0,
      "stale":0
   },
   "error":null
}
```

### `submit`

채굴자에 의해 시작되는 메시지입니다.
마이너가 쉐어를 찾았을때, 노드에게 보내집니다.

#### Request

채굴자는 Stratum 서버에 작업 솔루션을 보냅니다.

| Field         | Content                                                                     |
| :------------ | :-------------------------------------------------------------------------- |
| id            | 요청 ID                                                                      |
| jsonrpc       | "2.0"                                                                       |
| method        | "submit"                                                                    |
| params        | Int `edge_bits`,`nonce`, `height`, `job_id` and array of integers `pow`     |

예시:

``` JSON
{
   "id":"0",
   "jsonrpc":"2.0",
   "method":"submit",
   "params":{
      "edge_bits":29,
      "height":16419,
      "job_id":0,
      "nonce":8895699060858340771,
      "pow":[  
         4210040,10141596,13269632,24291934,28079062,84254573,84493890,100560174,100657333,120128285,130518226,140371663,142109188,159800646,163323737,171019100,176840047,191220010,192245584,198941444,209276164,216952635,217795152,225662613,230166736,231315079,248639876,263910393,293995691,298361937,326412694,330363619,414572127,424798984,426489226,466671748,466924466,490048497,495035248,496623057,502828197, 532838434
         ]
   }
}
```

#### Response

Response 는 세가지 타입이 될 수 있습니다.

##### OK response

이 타입은 Stratum 에 받아들여지지만 네트워크 타켓 난이도에서는 유효한 cuck(at)oo 솔루션이 아닙니다.

| Field         | Content                        |
| :------------ | :----------------------------- |
| id            | 요청 ID                         |
| jsonrpc       | "2.0"                          |
| method        | "submit"                       |
| result        | "ok"                           |
| error         | null                           |

예시:

``` JSON
{  
   "id":"2",
   "jsonrpc":"2.0",
   "method":"submit",
   "result":"ok",
   "error":null
}
```

##### Blockfound response

이 타입은 Stratum 에 받아들여지고 네트워크 타켓 난이도에서는 유효한 cuck(at)oo 솔루션 입니다.

| Field         | Content                        |
| :------------ | :----------------------------- |
| id            | 요청 ID                         |
| jsonrpc       | "2.0"                          |
| method        | "submit"                       |
| result        | "block - " + hash of the block |
| error         | null                           |

예시:

``` JSON
{  
   "id":"6",
   "jsonrpc":"2.0",
   "method":"submit",
   "result":"blockfound - 23025af9032de812d15228121d5e4b0e977d30ad8036ab07131104787b9dcf10",
   "error":null
}
```

##### Error response

에러 response는 stale과 rejected 라는 두가지 타입이 될 수 있습니다.

##### Stale share error response

이 타입은 유효한 솔루션이나 지난 작업이 현재의 것이 아닙니다.

| Field         | Content                                                   |
| :------------ | :-------------------------------------------------------- |
| id            | 요청 ID                                                    |
| jsonrpc       | "2.0"                                                     |
| method        | "submit"                                                  |
| error         | {"code":-32503,"message":"Solution submitted too late"}   |

Example:

```JSON
{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{  
      "code":-32503,
      "message":"Solution submitted too late"
   }
}
```

##### Rejected share error responses

솔루션이 유효하지 않거나 너무 낮은 난이도일 수 있는 두 가지 가능성이 있습니다.

###### Failed to validate solution error

재출된 솔루션이 유효하지 않을 수 았습니다.

| Field         | Content                                                   |
| :------------ | :-------------------------------------------------------- |
| id            | 요청 ID                                                    |
| jsonrpc       | "2.0"                                                     |
| method        | "submit"                                                  |
| error         | {"code":-32502,"message":"Failed to validate solution"}   |

Example:

```JSON
{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{  
      "code":-32502,
      "message":"Failed to validate solution"
   }
}
```

###### Share rejected due to low difficulty error

제출된 솔루션의 난이도가 너무 낮습니다.

| Field         | Content                                                          |
| :------------ | :--------------------------------------------------------------- |
| id            | 요청 ID                                                           |
| jsonrpc       | "2.0"                                                            |
| method        | "submit"                                                         |
| error         | {"code":-32501,"message":"Share rejected due to low difficulty"} |

Example:

```JSON
{  
   "id":"5",
   "jsonrpc":"2.0",
   "method":"submit",
   "error":{  
      "code":-32501,
      "message":"Share rejected due to low difficulty"
   }
}
```

## Error Messages

Grin Stratum protocole 구현체는 다음과 같은 에러 메시지를 포함하고 있습니다.

| Error code  | Error Message                          |
| :---------- | :------------------------------------- |
| -32000      | Node is syncing - please wait          |
| -32500      | Login first                            |
| -32501      | Share rejected due to low difficulty   |
| -32502      | Failed to validate solution            |
| -32503      | Solution Submitted too late            |
| -32600      | Invalid Request                        |
| -32601      | Method not found                       |

## Miner behavior

채굴자들은 반드시 다음과 같은 규칙들을 존중해야 할 것입니다.

- 마이너들은 작업을 시작하기 전에 작업 nounce를 랜덤화 시켜야 합니다.
- 채굴자들은 반드시 서버가 샤로운 작업을 보낼때끼지 같은 작업을 채굴해야 하지만 언제든 새로운 작업을 요청 할 수 있습니다.
- 채굴자들은 서버로 부터 온 작업 요청을 rpc response로 보내면 안됩니다.
- 채굴자들은 RPC "id"를 정할 수 있고 같은 id로 response를 받기를 요구 할 수 있습니다.
- 마이너들은 keepalive 메시지를 보낼수 있습니다.
- 채굴자들은 로그인 request를 보낼 수 있습니다.(어떤 채굴자가 쉐어를 찾았는지 확인하기 위해서 / Log안에서 솔루션을 확인하기 위해 ) 로그인 request는 3가지 파라미터를 가지고 있어야만 합니다.
- Miners MUST return the supplied job_id with submit messages.
- 채굴자들은 주어진 job_id를 제출하는 메시지에 리턴해야 합니다.

## Reference Implementation

현재 구현체는 [mimblewimble/grin-miner](https://github.com/mimblewimble/grin-miner/blob/master/src/bin/client.rs) 에서 참고하세요.