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.
-
class
protocoin.serializers.
GetAddr
¶ The getaddr command.
-
class
protocoin.serializers.
GetAddrSerializer
¶ The serializer for the getaddr command.
-
class
protocoin.serializers.
GetBlocks
(hashes)¶ The getblocks command.
-
class
protocoin.serializers.
GetData
¶ GetData message command.
-
class
protocoin.serializers.
GetDataSerializer
¶ Serializer for the GetData command.
-
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.
-
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.
-
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
-
static
-
class
protocoin.serializers.
NotFound
¶ NotFound command message.
-
class
protocoin.serializers.
NotFoundSerializer
¶ Serializer for the NotFound message.
-
class
protocoin.serializers.
OutPoint
¶ The OutPoint representation.
-
class
protocoin.serializers.
OutPointSerializer
¶ The OutPoint representation serializer.
-
class
protocoin.serializers.
Ping
¶ The ping command, which should always be answered with a Pong.
-
class
protocoin.serializers.
Pong
¶ The pong command, usually returned when a ping command arrives.
-
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.
-
classmethod
-
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.
-
class
protocoin.serializers.
TxOut
¶ The transaction output.
-
class
protocoin.serializers.
TxOutSerializer
¶ The transaction output serializer.
-
class
protocoin.serializers.
VerAck
¶ The version acknowledge (verack) command.
-
class
protocoin.serializers.
VerAckSerializer
¶ The serializer for the verack command.
-
class
protocoin.serializers.
Version
¶ The version command.
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
-
classmethod