11.2 Chia Pool Protocol 1.0 Specification
This is the initial version of the Chia Pool Protocol. It is designed to be simple, and to be extended later. It relies on farmers having smart coins (referred to as plot NFTs in GUI + CLI) which allow them to switch between pools by making transactions on the blockchain. Furthermore, it decreases the reliance on pools for block production, since the protocol only handles distribution of rewards, and it protects against pools or farmers acting maliciously.
Security considerations
The pool must ensure that partials arrive quickly, faster than the 28-second time limit of inclusion into the blockchain. This allows farmers that have slow setups to detect issues.
The Pool server must check that the pool_contract_puzzle_hash
a.k.a. p2_singleton_puzzle_hash
matches the puzzle that they expect. Otherwise, the pool has no guarantee that users will not attempt to claim block rewards for themselves, and immediately leave the pool, something that the provided smart contract prevents.
The Chia client must only connect to the pool configuration URL via HTTPS over TLS >= 1.2. This is to prevent session hijacking, leading to user funds being stolen.
Parties
The parties involved in the pool protocol are the pool operator and farmers. Each farmer is running a farmer process, and any number of harvester processes connected to that farmer process. The full node can either be run by the farmer (the default in the Chia GUI application), or run by the pool operator. If the farmer does not want to run a full node, they can configure their node to connect to a remote full node.
A pool operator can support any number of farmers.
Farmer identification
A farmer can be uniquely identified by the identifier of the farmer's singleton on the blockchain, this is what launcher_id
refers to. The launcher_id
can be used as a primary key in a database. The pool must periodically check the singleton's state on the blockchain to validate that it's farming to the pool, and not leaving or farming to another pool.
Farmer authentication
For the farmer to authenticate to the pool the following time based authentication token scheme must be added to the signing messages of some endpoints.
authentication_token = current_utc_minutes / authentication_token_timeout
Where authentication_token_timeout
is a configuration parameter of the pool which is also included in the GET /pool_info response that must be respected by the farmer. Whereas current_utc_minutes
is the local UTC timestamp in minutes at the moment of signing. The local clock should ideally be in sync with a time synchronization protocol e.g., NTP. The authentication token is usually included in a signed payload.
HTTPS Endpoints Summary
The pool protocol consists of several HTTPS endpoints which return JSON responses. The HTTPS server can run on any port, but must be running with TLS enabled (using a CA approved certificate), and with pipelining enabled. All bytes values are encoded as hex with optional 0x in front. Clients are also expected to run with pipelining.
Error codes
A failed endpoint will always return a JSON object with an error code and an english error message as shown below:
{ "error_code": 0, "error_message": "" }
The following errors may occur:
Error code | Description |
---|---|
0x01 | The provided signage point has been reverted |
0x02 | Received partial too late |
0x03 | Not found |
0x04 | Proof of space invalid |
0x05 | Proof of space not good enough |
0x06 | Invalid difficulty |
0x07 | Invalid signature |
0x08 | Web-Server raised an exception |
0x09 | Invalid puzzle hash |
0x0A | Farmer not known |
0x0B | Farmer already known |
0x0C | Invalid authentication public key |
0x0D | Invalid payout instructions |
0x0E | Invalid singleton |
0x0F | Delay time too short |
0x10 | Request failed |
Signature validation
Most of the endpoints require signature validation. The validation requires serialization of the endpoints payloads to calculate the message hash which is done like:
message_hash = sha256(serialized_payload)
The serialized payload must follow the format defined in the Streamable
class.
Pool URL
The pool URL is the url that farmers use to connect to the pool. The subdomains, port, and path are optional. The client will use 443 if there is no port. Note that the trailing slash must NOT be present. Everything must be lower case.
https://subdomain.domain.tld:port/path