P2Pool code documentation

Ignore this page for the minute. Is just a scratch pad for documenting the p2pool code. Will tidy up once initial pass done.

Files

Files Name	Description
p2pool/main.py	Main Startup and initialisation code
p2pool/data.py	P2Pool main data structures
p2pool/util/pack.py	Handling of over the wire data structures

p2pool/main.py

Makes extensive use of twisted.defer. This allows it to "yield" to allow long running network code to complete. Read up on Python Generators and this before progressing!

Contains main startup code.

Function run

This is the initially executed function.

1. Parses arguments
2. Reads user/password from bitcoin config file
3. Sets up log file
4. Sets up logger that reports errors to http://u.forre.st/p2pool_error.cgi (If you are concerned this is a privacy issue add --no-bugreport to command line.)

Finally it adds the main function to the Twister Reactor and start the reactor. (i.e. runs the function main!).

main

This does all the startup tasks.

1. Tests connection to bitcoind.
2. Prints hash of latest block to show bitcoind is up to date.
3. Tests connection to p2pool network.
4. Gets address to use for payout either from file or bitcoind.
5. Validates address and checks local bitcoind owns it.
6. Create a "tracker" and loads know shares from files in data/bitcoin/sharesX where X is a number.
7. poll_bitcoind then gets work from bitcoind (i.e. block header to hash). Does this by calling getwork function explained below.
8. I am still getting my head round Twisted but I think the work_poller() function then polls bitcoind every 15 seconds for new work.
9. Check for work from peers. This is new code to try to reduce stales. It gets new block headers from peers if they arrive before the ones from bitcoind.
10. Set up merged work for merged mining.
11. Sets up combined work.

p2pool/data.py

Contains the main data structures used in p2pool. These are:

hash_link_type

Serialized SHA256 engine state, used to prove that a coinbase transaction contains some data near the end without sending the entire transaction.

hash_link_type

Field	Type	Description
state	String(32)	?
extra_data	String(0)	Comments say this is a hack
length	VarInt	?

small_block_header

Bitcoin block header, excluding the merkle root. Included in shares, where the merkle root is computed implicitly from the coinbase transaction and the merkle branch.

small_block_header

Field	Type	Description
version	VarInt	?
previous_block	None or Int(256)	?
timestamp	Int(32)	?
bits	FloatingInteger(32)	?
nonce	Int(32)	?

share_data_type

Information contained within a share that is only relevant to P2Pool and that the client has control over (i.e. its value isn't fixed by the protocol rules).

share_data_type

Field	Type	Description
previous_share_hash	None or int(256)	?
coinbase	VarString	?
nonce	Int(32)	?
pubkey_hash	Int(160)	?
subsidy	Int(64)	?
donation	Int(16)	?
stale_info	String(32)	Enum (orpan, dao, unk253, unk252...???
desired_version	VarInt	?

share_info_type

Information contained within a share that is only relevant to P2Pool

share_info_type

Field	Type	Description
share_data	share_data_type (see above)	?
far_share_hash	none or int(256)	?
max_bits	Float Int	?
bits	Float Int	?
timestamp	Int(32)	?

x

x

Field	Type	Description
name	String(32)	?

x

x

Field	Type	Description
name	String(32)	?

x

x

Field	Type	Description
name	String(32)	?

p2pool/util/pack.py

I think this handles all the binary data types used in the bitcoin protocol to send data over the network wire. These are nasty as very low level and many big endian/little endian complications. The p2pool network protocol uses these also. Do not think you need to really understand this unless making changes at this low level.

p2pool/__init__.py

At bottom has DEBUG flag. Change to true to get more output. (running p2pool with --debug does this) Other than that just returns version number for git if it can.