Pooling Protocol

Notes

• MMX addresses are encoded via bech32 string
• Hashes and signatures are encoded via little-endian upper-case hex string, without 0x prefix
• Account address = Payout address

Pool Server API

POST /partial

Endpoint to post a partial.

Content-Type: application/json

Payload: Object

• height: Block height the proof is for
• hash: Message hash for signature (see below)
• contract: Plot NFT address
• account: Payout address (can be multiple per NFT, first partial creates account)
• pool_url: The base URL used to make this request
• harvester: Harvester name, usually hostname
• lookup_time_ms: Harvester lookup time (ms)
• proof: Proof, can be Proof of Space or Proof of Stake (see below)
• farmer_sig: Farmer signature based on hash and proof.farmer_key
• __type: mmx.Partial

The proof is an object as follows:

• __type: Proof type (always mmx.ProofOfSpaceNFT)
• score: Proof score
• plot_id: Plot ID
• challenge: challenge hash for this height and fork
• difficulty: Partial difficulty used when performing lookup (might be different than current setting)
• farmer_key: Farmer Public Key

For proof.__type == mmx.ProofOfSpaceNFT the following additional fields will be present:

• ksize: Plot k-size
• seed: Plot random seed
• proof_xs: List of proof X values (256)
• contract: Plot NFT contract address

Returns status 200 with application/json object as follows:

• error_code: Integer error code (see below)
• error_message: Message string

Example partial

TODO: update

{
  __type: 'mmx.Partial',
  account: 'mmx1kx69pm743rshqac5lgcstlr8nq4t93hzm8gumkkxmp5y9fglnkes6ve09z',
  challenge: 'CA98DB6504B2C85D876BEC1881F41E805D49FDE33DFE548A26C3277CFAE7EFF9',
  contract: 'mmx19hxc7mfkdalx0khe5nr4r50t338z8sg4avn7vqu7ts4mpkxeg0lqhesvzl',
  farmer_sig: '3CDCD57B151254835100F47F16834F91ED87838F5C68E113F236FD88169133643D06A4D50B6FB96859BECB73A73CE0E449262717B9907E70F05659F487C14F4B',
  harvester: 'prime',
  hash: 'B7269935091572E1004B48C327EEF2070DA0176A94AE2129AD8E68A9059FD95F',
  height: 845490,
  lookup_time_ms: 82,
  difficulty: 1,
  pool_url: 'http://localhost:8080',
  proof: {
    __type: 'mmx.ProofOfSpaceNFT',
    contract: 'mmx19hxc7mfkdalx0khe5nr4r50t338z8sg4avn7vqu7ts4mpkxeg0lqhesvzl',
    farmer_key: '027D7562FB5A8967E57A22F876302F75BA3AE3980607FB32E4439681F820AE398F',
    ksize: 26,
    plot_id: '22F0CA184633E07F32C5289B0ACF39597637CD6685D3CD4E7CD87CD56FAF8761',
    proof_xs: [
      61796699, 13346431, 24374059, 22439072, 65129000, 58802027,
      ... 250 more items
    ],
    score: 25993,
    seed: '091B11F9A066A9120AAD4BF8D30D933E4CED2EB3BF2CCA1DA72D8BA8E68BDA96'
  }
}

GET /difficulty

Returns current partial difficulty. If farmer account does not exist yet, it should return a default starting difficulty.

Will be polled by farmers every 300 sec by default.

Query parameters:

• id: Farmer account address (payout address)

Always returns status 200 with application/json object as follows:

• difficulty: Integer value

POST /set_difficulty

Endpoint for custom partial difficulty settings. Support for this is optional.

Partial difficulty is set per account (ie. payout address), not per plot NFT.

Content-Type: application/json

Payload: Object

• account: Account address
• type: static or dynamic
• value: Static difficulty value, or partials per hour (integer) in case of dynamic
• time: POSIX timestamp in seconds
• public_key: Public key for account address
• signature: Signature for message and public_key

Returns status 200 with application/json object as follows:

• error_code: Integer error code (see below)
• error_message: Message string

GET /pool/info

Returns pool information as application/json object:

• name
• description
• fee: Pool fee (0 to 1, 1 = 100%)
• logo_path: Relative path for logo image, starting with /.
• protocol_version: 1
• pool_target: Plot NFT target address
• min_difficulty: Lowest partial difficulty that is supported

GET /pool/stats

Returns pool statistics as application/json object:

• estimated_space: Estimated pool size in TB
• partial_rate: Partials / hour
• farmers: Number of active farmers

GET /account/info

Query parameters:

• id: Farmer account address (payout address)

Returns account info as application/json object:

• balance: Current unpaid balance [MMX]
• total_paid: Total amount paid out so far [MMX]
• difficulty: Partial difficulty
• pool_share: Relative farm size to pool (0 to 1)
• partial_rate: Partials / hour
• blocks_found: Number of blocks farmed
• estimated_space: Estimated farm size in TB

Node API

POST /wapi/node/verify_partial

Endpoint to verify a partial, optionally with plot NFT verification.

Note

Partials should be verfied after a certain delay, for example once the height of the partial has been reached on-chain. Partials are computed 6 blocks in advance, so waiting until the partial’s height has been reached will give 6 blocks security. Even in case of a re-org larger than 6 blocks, the chance a partial won’t be valid anymore is only ~5%.

Content-Type: application/json

Payload: Object

• partial: The same object as was received by the pool via POST /partial.
• pool_target: Expected plot NFT target address (optional)
  • When specified will verify plot NFT is locked to given target address at current blockchain height.

Returns status 200 with application/json object as follows:

• error_code: Integer error code (see below)
• error_message: Message string

When the node is not synced will return status 500 with error text.

POST /wapi/node/verify_plot_nft_target

Endpoint to verify that a plot NFT is locked and pointed to the given target address at the current blockchain height.

Content-Type: application/json

Payload: Object

• address: Plot NFT address
• pool_target: Expected plot NFT target address

Returns status 200 with application/json object as follows:

• error_code: Integer error code (see below)
• error_message: Message string

When the node is not synced will return status 500 with error text.

Message hash algorithm

A string is generated for JSON objects as follows:

• First the __type field is added, followed with /
• Then for each field in the specified order:
  • The field name is added, followed with a :
  • The field value is added (floating point values are floored first)
• For any nested objects, the same scheme is followed.

The final string is hashed via SHA2-256.

Error Codes

Error codes are transferred as strings in JSON:

• NONE: No error
• INVALID_PARTIAL
• DUPLICATE_PARTIAL
• PARTIAL_TOO_LATE
• PARTIAL_NOT_GOOD_ENOUGH
• CHALLENGE_REVERTED
• CHALLENGE_NOT_FOUND
• INVALID_PROOF
• INVALID_DIFFICULTY
• INVALID_SIGNATURE
• INVALID_CONTRACT
• INVALID_AUTH_KEY
• INVALID_ACCOUNT
• INVALID_TIMESTAMP
• POOL_LOST_SYNC
• SERVER_ERROR