Difference between revisions of "BIP PoolAPI"

From Bitcoin Wiki
Jump to: navigation, search
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
                        {{bip}}
 +
 +
<pre>
 +
  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
 +
</pre>
 +
 +
==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===
 
{| class="wikitable"
 
{| class="wikitable"
−
! Key !! Required !! Type !! Description
+
! Key !! Type !! Description
 +
|-
 +
!colspan='3'| Root
 +
|-
 +
| version || Number || always 1
 +
|-
 +
| group || Object || information about the organizational pool
 +
|-
 +
| collab || Array of Objects || information about each collaborative pool
 +
|-
 +
!colspan='3'| 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
 +
|-
 +
!colspan='3'| 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
 +
|-
 +
!colspan='3'| 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
 +
|-
 +
!colspan='3'| Shares
 +
|-
 +
! Key !! Type !! Description
 +
|-
 +
| accepted || Number || number of accepted shares
 +
|-
 +
| * || Number || any [[BIP 0022#Example Rejection Reasons|rejection reason]] may be a key; value is number of shares
 +
|-
 +
!colspan='3'| 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
 
|-
 
|-
−
| version || {{Yes}} || Number || always 1
+
| balances || Array of Objects || balance information
 
|-
 
|-
−
| group || {{No}} || Object || information about the organizational pool
+
| fee || Number || fee (0.01 = 1%)
 
|-
 
|-
−
| collab || {{No}} || Array of Objects || information about each collaborative pool
+
| hashrate || Number || total hashrate of all mining in the same collaborative pool
−
|}
+
|-
−
 
+
| lastactive || Number || time the miner was last seen active
−
Organizational pool:
+
|-
−
{| class="wikitable"
+
| rewardalgo || String || reward algorithm identifier
−
! Key !! Required !! Type !! Description
+
|-
 +
| 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
 +
|-
 +
!colspan='3'| Balance info
 +
|-
 +
! Key !! Type !! Description
 +
|-
 +
| currency || String || currency of balance
 +
|-
 +
| balance || Number || amount currently stored at the pool
 
|-
 
|-
−
| name || {{No}} || String || human-readable identifier for organizational pool
+
| unconfirmed || Number || amount currently waiting for confirmations
 
|-
 
|-
−
| hashrate || {{No}} || Number || total hashrate of all mining in the organizational pool
+
| estimate || Number || amount expected reward for the current round
 
|-
 
|-
−
| miners || {{No}} || Array of Objects || information of specific miners
+
| fee || Number || fee (0.01 = 1%)
−
|}
 
−
 
 
−
Collaborative pool:
 
−
{| class="wikitable"
 
−
! Key !! Required !! Type !! Description
 
 
|-
 
|-
−
| name || {{No}} || String || human-readable identifier for collaborative pool
+
| paid || Number || amount that has been paid out ever
 
|-
 
|-
−
| hashrate || {{No}} || Number || total hashrate of all mining in the same collaborative pool
+
| lastpay || Number || amount of last payout
 
|-
 
|-
−
| roundbegin || {{No}} || Number || time the current round began
+
| lastpaytime || Number || time of last payout
 
|-
 
|-
−
| roundshares || {{No}} || Number || number of shares submitted to the current round
+
| autopay || Number || minimum amount before autopayout
 
|-
 
|-
−
| miners || {{No}} || Array of Objects || information of specific miners
+
| autopayto || String || address for autopayouts
 
|}
 
|}
  
−
Individual miner:
+
Currencies:
 
{| class="wikitable"
 
{| class="wikitable"
−
! Key !! Required !! Type !! Description
+
! Currency name !! Description
 
|-
 
|-
−
| id || {{No}} || String || unique identifier for a miner's account (shared across collaborative pools)
+
| Bitcoin || Bitcoins (in Satoshis)
 
|-
 
|-
−
| name || {{No}} || String || human-readable identifier for miner
+
| Namecoin || Namecoins
 
|-
 
|-
−
| balances || {{No}} || Array of Objects || balance information
+
| fiat || Pool-specific "play money" (eg, SMPPS "extra credit")
−
|-
+
|}
−
| hashrate || {{No}} || Number || total hashrate of all mining in the same collaborative pool
+
 
 +
Networks:
 +
{| class="wikitable"
 +
! Network name !! Description
 
|-
 
|-
−
| lastactive || {{No}} || Number || time the miner was last seen active
+
| Bitcoin || Bitcoin blockchain
 
|-
 
|-
−
| roundshares || {{No}} || Number || number of shares submitted to the current round
+
| Bitcoin address || Searching for vanity Bitcoin addresses
 
|-
 
|-
−
| workers || {{No}} || Array of Objects || information of specific workers
+
| Namecoin || Namecoin blockchain
 
|}
 
|}
  
−
Balance info:
+
Reward algorithms:
−
{|
+
{| class="wikitable"
−
! Key !! Required !! Type !! Description
+
! Algorithm name !! Description
 +
|-
 +
| Prop || Proportional
 
|-
 
|-
−
| currency || {{No}} || String || currency of balance
+
| PPLNS || Pay Per Last N Shares
 
|-
 
|-
−
| balance || {{No}} || Number || amount currently stored at the pool
+
| PPS || Pay Per Share
 
|-
 
|-
−
| estimate || {{No}} || Number || amount expected reward for the current round
+
| SMPPS || Shared Maximum Pay Per Share
 
|-
 
|-
−
| paid || {{No}} || Number || amount that has been paid out ever
+
| Score ||
 
|-
 
|-
−
| lastpay || {{No}} || Number || amount of last payout
+
| Geo || Geometric Method
 
|-
 
|-
−
| lastpaytime || {{No}} || Number || time of last payout
+
| DGM || Double Geometric Method
 
|}
 
|}
  
−
Note: Bitcoin balances are in Satoshis
+
===Example===
 +
<pre>
 +
{
 +
"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
 +
}
 +
}
 +
]
 +
]
 +
}
 +
]
 +
}</pre>
 +
 
 +
==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.

Latest revision as of 03:21, 7 June 2012

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.

Retrieved from "https://tests.bitcoin.it/w/index.php?title=BIP_PoolAPI&oldid=27516"