BIP PoolAPI

This page describes a BIP (Bitcoin Improvement Proposal). Please see BIP 2 for more information about BIPs and creating them. Please do not just create a wiki page.

  BIP: ?
  Title: JSON Pool Information API
  Author: Paul Sheppard <shepsoft@gmail.com> and Luke Dashjr <luke+bip22@dashjr.org>
  Status: Draft
  Type: Standards Track
  Created: 22-05-2012

Abstract

This BIP aims to create a standard API for pool statistics.

Specification

• All time keys are seconds since Jan 1 1970 midnight UTC.
• Hashrate is measured in full block hashes per second. So if a full block proof-of-work requires two rounds of SHA256 (as it does with Bitcoin today), each two rounds counts only as a single hash.
• Currencies are always represented in the smallest divisible part of the currency. eg, for USD this is 1 cent and for Bitcoin this is 0.00000001 BTC

Object Formats

Key	Type	Description
Root
version	Number	always 1
group	Object	information about the organizational pool
collab	Array of Objects	information about each collaborative pool
Organizational pool
Key	Type	Description
name	String	human-readable identifier for organizational pool
hashrate	Number	total hashrate of all mining in the organizational pool
message	String	whatever the pool wants to tell us
minercount	Number	total number of active miners
miners	Array of Objects	information of specific miners
workercount	Number	total number of active workers
Collaborative pool
Key	Type	Description
name	String	human-readable identifier for collaborative pool
hashrate	Number	total hashrate of all mining in the same collaborative pool
message	String	whatever the pool wants to tell us
round	Object	information about the current round
fee	Number	fee (0.01 = 1%)
rewardalgo	String	reward algorithm identifier
minercount	Number	total number of active miners
miners	Array of Objects	information of specific miners
time	Number	time as the poolserver sees it
workercount	Number	total number of active workers
Round
Key	Type	Description
id	String	unique identifier for the round
begintime	Number	time the current round began
shares	Object	number of shares submitted to the current round
network	String	which network the round is relevant for
parent	String	network-specific identifier for the base of the current round
Shares
Key	Type	Description
accepted	Number	number of accepted shares
*	Number	any rejection reason may be a key; value is number of shares
Individual miner or worker
Key	Type	Description
id	String	unique identifier for a miner's account (shared across collaborative pools)
name	String	human-readable identifier for miner
message	String	whatever the pool wants to tell us
balances	Array of Objects	balance information
fee	Number	fee (0.01 = 1%)
hashrate	Number	total hashrate of all mining in the same collaborative pool
lastactive	Number	time the miner was last seen active
rewardalgo	String	reward algorithm identifier
sharesround	Object	information on shares submitted to the current round
sharesuser	Object	information on shares submitted since last user reset
sharestotal	Object	information on shares submitted for all time
workers	Array of Objects	information of specific workers
Balance info
Key	Type	Description
currency	String	currency of balance
balance	Number	amount currently stored at the pool
unconfirmed	Number	amount currently waiting for confirmations
estimate	Number	amount expected reward for the current round
fee	Number	fee (0.01 = 1%)
paid	Number	amount that has been paid out ever
lastpay	Number	amount of last payout
lastpaytime	Number	time of last payout
autopay	Number	minimum amount before autopayout
autopayto	String	address for autopayouts

Currencies:

Currency name	Description
Bitcoin	Bitcoins (in Satoshis)
Namecoin	Namecoins
fiat	Pool-specific "play money" (eg, SMPPS "extra credit")

Networks:

Network name	Description
Bitcoin	Bitcoin blockchain
Bitcoin address	Searching for vanity Bitcoin addresses
Namecoin	Namecoin blockchain

Reward algorithms:

Algorithm name	Description
Prop	Proportional
PPLNS	Pay Per Last N Shares
PPS	Pay Per Share
SMPPS	Shared Maximum Pay Per Share
Score
Geo	Geometric Method
DGM	Double Geometric Method

Example

{
	"version": 1,
	"group": {
		"name": "Eligius",
		"hashrate": 600000000000,
		"message": "Welcome to Eligius! Enjoy :)"
	},
	"collab": [
		{
			"name": "Eligius-Ra",
			"hashrate": 550000000000,
			"time": 1337729874.2489,
			"workercount": 5423,
			"round": {
				"begintime": 1337719877.959086,
				"blockchain": "Bitcoin",
				"blockparent": "00000000000001c536f8865bd2be554372fa149eb88fb1c096f475e1c9cd8176",
				"shares": {
					"accepted": 423433,
					"stale-prevblk": 92,
					"duplicate": 3
				}
			},
			"fee": 0,
			"rewardalgo": "SMPPS",
			"miners": [
				"id": "16kNKa7WUg8QAPFy8dJRv7USSu2fAG2pkW",
				"name": "Luke-Jr",
				"balances": [
					{
						"currency": "Bitcoin",
						"balance": 167476453,
						"estimate": 14761828,
						"paid": 5800000000,
						"lastpay": 67423840,
						"lastpaytime": 1337713832.25908
					},
					{
						"currency": "fiat",
						"balance": 9342224,
						"estimate": 39433
					}
				],
				"hashrate": 1382848482,
				"lastactive": 1337783882.423086,
				"sharesround": {
					"accepted": 832
				},
				"workers": [
					{
						"id": "16kNKa7WUg8QAPFy8dJRv7USSu2fAG2pkW_Icarus",
						"name": "Luke-Jr's Icarus :)",
						"hashrate": 378483883,
						"lastactive": 1337783882.423086,
						"sharesround": {
							"accepted": 100
						}
					},
					{
						"id": "16kNKa7WUg8QAPFy8dJRv7USSu2fAG2pkW_BFL",
						"name": "Luke-Jr's BitForce Single :D",
						"hashrate": 832942393,
						"lastactive": 1337783882.423086,
						"sharesround": {
							"accepted": 600
						}
					},
					{
						"id": "16kNKa7WUg8QAPFy8dJRv7USSu2fAG2pkW_6870",
						"name": "Luke-Jr's Radeon 6870",
						"hashrate": 371422206,
						"lastactive": 1337783882.423086,
						"sharesround": {
							"accepted": 232
						}
					}
				]
			]
		}
	]
}

Motivation

Moving forward with bitcoin it is important to make all aspects as user friendly as possible.

Rationale

This BIP allows the creators of Apps and Web GUIs for pool monitoring a common interface to use, as opposed to dealing with a differing interface for each pool.

Backwards Compatibility

As an emerging standard, backwards comparability is not applicable. However forward comparability should be maintained. Any future incompatibilities shall be identified by the 'API_version' number.