API Documentation

All modules listed below are under the “protocoin” module.

protocoin.fields – Fields

class protocoin.fields.BlockLocator

A block locator type used for getblocks and getheaders

class protocoin.fields.Field

Base class for the Fields. This class only implements the counter to keep the order of the fields on the serializer classes.

deserialize(stream)

This method must read the stream data and then deserialize and return the deserialized content.

Returns:the deserialized content
Parameters:stream – stream of data to read
parse(value)

This method should be implemented to parse the value parameter into the field internal representation.

Parameters:value – value to be parsed
serialize()

Serialize the internal representation and return the serialized data.

Returns:the serialized data
class protocoin.fields.FixedStringField(length)

A fixed length string field.

Example of use:

class MessageHeaderSerializer(Serializer):
    model_class = MessageHeader
    magic = fields.UInt32LEField()
    command = fields.FixedStringField(12)
    length = fields.UInt32LEField()
    checksum = fields.UInt32LEField()
class protocoin.fields.Hash

A hash type field.

class protocoin.fields.IPv4AddressField

An IPv4 address field without timestamp and reserved IPv6 space.

class protocoin.fields.Int16LEField

16-bit little-endian integer field.

class protocoin.fields.Int32LEField

32-bit little-endian integer field.

class protocoin.fields.Int64LEField

64-bit little-endian integer field.

class protocoin.fields.ListField(serializer_class)

A field used to serialize/deserialize a list of serializers.

Example of use:

class TxSerializer(Serializer):
    model_class = Tx
    version = fields.UInt32LEField()
    tx_in = fields.ListField(TxInSerializer)
    tx_out = fields.ListField(TxOutSerializer)
    lock_time = fields.UInt32LEField()
class protocoin.fields.NestedField(serializer_class)

A field used to nest another serializer.

Example of use:

class TxInSerializer(Serializer):
    model_class = TxIn
    previous_output = fields.NestedField(OutPointSerializer)
    signature_script = fields.VariableStringField()
    sequence = fields.UInt32LEField()
class protocoin.fields.PrimaryField

This is a base class for all fields that has only one value and their value can be represented by a Python struct datatype.

Example of use:

class UInt32LEField(PrimaryField):
    datatype = "<I"
deserialize(stream)

Deserialize the stream using the struct data type specified.

Parameters:stream – the data stream
parse(value)

This method will set the internal value to the specified value.

Parameters:value – the value to be set
serialize()

Serialize the internal data and then return the serialized data.

class protocoin.fields.UInt16BEField

16-bit big-endian unsigned integer field.

class protocoin.fields.UInt16LEField

16-bit little-endian unsigned integer field.

class protocoin.fields.UInt32LEField

32-bit little-endian unsigned integer field.

class protocoin.fields.UInt64LEField

64-bit little-endian unsigned integer field.

class protocoin.fields.VariableIntegerField

A variable size integer field.

class protocoin.fields.VariableStringField

A variable length string field.

protocoin.serializers – Serializers

class protocoin.serializers.AddressVector

A vector of addresses.

class protocoin.serializers.AddressVectorSerializer

Serializer for the addresses vector.

model_class

alias of AddressVector

class protocoin.serializers.Block

The block message. This message contains all the transactions present in the block.

class protocoin.serializers.BlockHeader

The header of the block.

calculate_hash()

This method will calculate the hash of the block.

class protocoin.serializers.BlockHeaderSerializer

The serializer for the block header.

model_class

alias of BlockHeader

class protocoin.serializers.BlockSerializer

The deserializer for the blocks.

model_class

alias of Block

class protocoin.serializers.GetAddr

The getaddr command.

class protocoin.serializers.GetAddrSerializer

The serializer for the getaddr command.

model_class

alias of GetAddr

class protocoin.serializers.GetBlocks(hashes)

The getblocks command.

class protocoin.serializers.GetData

GetData message command.

class protocoin.serializers.GetDataSerializer

Serializer for the GetData command.

model_class

alias of GetData

class protocoin.serializers.HeaderVector

The header only vector.

class protocoin.serializers.HeaderVectorSerializer

Serializer for the block header vector.

model_class

alias of HeaderVector

class protocoin.serializers.IPv4Address

The IPv4 Address (without timestamp).

class protocoin.serializers.IPv4AddressSerializer

Serializer for the IPv4Address.

model_class

alias of IPv4Address

class protocoin.serializers.IPv4AddressTimestamp

The IPv4 Address with timestamp.

class protocoin.serializers.IPv4AddressTimestampSerializer

Serializer for the IPv4AddressTimestamp.

model_class

alias of IPv4AddressTimestamp

class protocoin.serializers.Inventory

The Inventory representation.

type_to_text()

Converts the inventory type to text representation.

class protocoin.serializers.InventorySerializer

The serializer for the Inventory.

model_class

alias of Inventory

class protocoin.serializers.InventoryVector

A vector of inventories.

class protocoin.serializers.InventoryVectorSerializer

The serializer for the vector of inventories.

model_class

alias of InventoryVector

class protocoin.serializers.MemPool

The mempool command.

class protocoin.serializers.MemPoolSerializer

The serializer for the mempool command.

model_class

alias of MemPool

class protocoin.serializers.MessageHeader(coin='bitcoin')

The header of all bitcoin messages.

class protocoin.serializers.MessageHeaderSerializer

Serializer for the MessageHeader.

static calc_checksum(payload)

Calculate the checksum of the specified payload.

Parameters:payload – The binary data payload.
model_class

alias of MessageHeader

class protocoin.serializers.NotFound

NotFound command message.

class protocoin.serializers.NotFoundSerializer

Serializer for the NotFound message.

model_class

alias of NotFound

class protocoin.serializers.OutPoint

The OutPoint representation.

class protocoin.serializers.OutPointSerializer

The OutPoint representation serializer.

model_class

alias of OutPoint

class protocoin.serializers.Ping

The ping command, which should always be answered with a Pong.

class protocoin.serializers.PingSerializer

The ping command serializer.

model_class

alias of Ping

class protocoin.serializers.Pong

The pong command, usually returned when a ping command arrives.

class protocoin.serializers.PongSerializer

The pong command serializer.

model_class

alias of Pong

class protocoin.serializers.Serializer

The main serializer class, inherit from this class to create custom serializers.

Example of use:

class VerAckSerializer(Serializer):
    model_class = VerAck
deserialize(stream)

This method will read the stream and then will deserialize the binary data information present on it.

Parameters:stream – A file-like object (StringIO, file, socket, etc.)
serialize(obj, fields=None)

This method will receive an object and then will serialize it according to the fields declared on the serializer.

Parameters:obj – The object to serializer.
class protocoin.serializers.SerializerABC

The serializer abstract base class.

class protocoin.serializers.SerializerMeta

The serializer meta class. This class will create an attribute called ‘_fields’ in each serializer with the ordered dict of fields present on the subclasses.

classmethod get_fields(meta, bases, attrs, field_class)

This method will construct an ordered dict with all the fields present on the serializer classes.

class protocoin.serializers.Tx

The main transaction representation, this object will contain all the inputs and outputs of the transaction.

calculate_hash()

This method will calculate the hash of the transaction.

class protocoin.serializers.TxIn

The transaction input representation.

class protocoin.serializers.TxInSerializer

The transaction input serializer.

model_class

alias of TxIn

class protocoin.serializers.TxOut

The transaction output.

class protocoin.serializers.TxOutSerializer

The transaction output serializer.

model_class

alias of TxOut

class protocoin.serializers.TxSerializer

The transaction serializer.

model_class

alias of Tx

class protocoin.serializers.VerAck

The version acknowledge (verack) command.

class protocoin.serializers.VerAckSerializer

The serializer for the verack command.

model_class

alias of VerAck

class protocoin.serializers.Version

The version command.

class protocoin.serializers.VersionSerializer

The version command serializer.

model_class

alias of Version

protocoin.clients – Clients

class protocoin.clients.BitcoinBasicClient(socket)

The base class for a Bitcoin network client, this class implements utility functions to create your own class.

Parameters:socket – a socket that supports the makefile() method.
close_stream()

This method will close the socket stream.

handle_message_header(message_header, payload)

This method will be called for every message before the message payload deserialization.

Parameters:
  • message_header – The message header
  • payload – The payload of the message
loop()

This is the main method of the client, it will enter in a receive/send loop.

send_message(message)

This method will serialize the message using the appropriate serializer based on the message command and then it will send it to the socket stream.

Parameters:message – The message object to send
class protocoin.clients.BitcoinClient(socket)

This class implements all the protocol rules needed for a client to stay up in the network. It will handle the handshake rules as well answer the ping messages.

handle_ping(message_header, message)

This method will handle the Ping message and then will answer every Ping message with a Pong message using the nonce received.

Parameters:
  • message_header – The header of the Ping message
  • message – The Ping message
handle_version(message_header, message)

This method will handle the Version message and will send a VerAck message when it receives the Version message.

Parameters:
  • message_header – The Version message header
  • message – The Version message
handshake()

This method will implement the handshake of the Bitcoin protocol. It will send the Version message.

protocoin.util – Utility

protocoin.util.base58_decode(address)

This function converts an base58 string to a numeric format.

Parameters:address – The base58 string
Returns:The numeric value decoded
protocoin.util.base58_encode(address_bignum)

This function converts an address in bignum formatting to a string in base58, it doesn’t prepend the ‘1’ prefix for the Bitcoin address.

Parameters:address_bignum – The address in numeric format
Returns:The string in base58
protocoin.util.services_to_text(services)

Converts the services field into a textual representation.

protocoin.keys – Keys and Address Management

class protocoin.keys.BitcoinPrivateKey(hexkey=None, entropy=None)

This is a representation for Bitcoin private keys. In this class you’ll find methods to import/export keys from multiple formats. Use a hex string representation to construct a new Public Key or use the clas methods to import from another format. If no parameter is specified on the construction of this class, a new Private Key will be created.

Parameters:
  • hexkey – The key in hex string format
  • entropy – A function that accepts a parameter with the number of bytes and returns the same amount of bytes of random data, use a good source of entropy. When this parameter is ommited, the OS entropy source is used.
classmethod from_string(klass, stringkey)

This method will create a new Private Key using the specified string data.

Parameters:stringkey – The key in string format
Returns:A new Private Key
classmethod from_wif(klass, wifkey)

This method will create a new Private Key from a WIF format string.

Parameters:wifkey – The private key in WIF format
Returns:A new Private Key
generate_public_key()

This method will create a new Public Key based on this Private Key.

Returns:A new Public Key
to_hex()

This method will convert the Private Key to a hex string representation.

Returns:Hex string representation of the Private Key
to_string()

This method will convert the Private Key to a string representation.

Returns:String representation of the Private Key
to_wif()

This method will export the Private Key to WIF (Wallet Import Format).

:returns:: The Private Key in WIF format.

class protocoin.keys.BitcoinPublicKey(hexkey)

This is a representation for Bitcoin public keys. In this class you’ll find methods to import/export keys from multiple formats. Use a hex string representation to construct a new public key or use the clas methods to import from another format.

Parameters:hexkey – The key in hex string format
classmethod from_private_key(klass, private_key)

This class method will create a new Public Key based on a private key.

Parameters:private_key – The private key
Returns:a new public key
to_address()

This method will convert the public key to a bitcoin address.

Returns:bitcoin address for the public key
to_hex()

This method will convert the public key to a hex string representation.

Returns:Hex string representation of the public key
to_string()

This method will convert the public key to a string representation.

Returns:String representation of the public key