Safe Haskell | None |
---|
This package provides all of the basic types used for the Bitcoin networking protocol together with Data.Binary instances for efficiently serializing and de-serializing them. More information on the bitcoin protocol is available here: http://en.bitcoin.it/wiki/Protocol_specification
- data Block = Block {
- blockHeader :: !BlockHeader
- blockCoinbaseTx :: !CoinbaseTx
- blockTxns :: ![Tx]
- type BlockLocator = [Hash256]
- data GetBlocks = GetBlocks {
- getBlocksVersion :: !Word32
- getBlocksLocator :: !BlockLocator
- getBlocksHashStop :: !Hash256
- data BlockHeader = BlockHeader {
- blockVersion :: !Word32
- prevBlock :: !Hash256
- merkleRoot :: !Hash256
- blockTimestamp :: !Word32
- blockBits :: !Word32
- bhNonce :: !Word32
- data GetHeaders = GetHeaders {
- getHeadersVersion :: !Word32
- getHeadersBL :: !BlockLocator
- getHeadersHashStop :: !Hash256
- data Headers = Headers {
- headersList :: ![BlockHeaderCount]
- type BlockHeaderCount = (BlockHeader, VarInt)
- blockid :: BlockHeader -> Hash256
- data GetData = GetData {
- getDataList :: ![InvVector]
- data Inv = Inv {}
- data InvVector = InvVector {}
- data InvType
- = InvError
- | InvTx
- | InvBlock
- | InvMerkleBlock
- data NotFound = NotFound {
- notFoundList :: ![InvVector]
- data Script = Script {}
- data ScriptOp
- = OP_PUSHDATA ByteString PushDataType
- | OP_0
- | OP_1NEGATE
- | OP_1
- | OP_2
- | OP_3
- | OP_4
- | OP_5
- | OP_6
- | OP_7
- | OP_8
- | OP_9
- | OP_10
- | OP_11
- | OP_12
- | OP_13
- | OP_14
- | OP_15
- | OP_16
- | OP_VERIFY
- | OP_DUP
- | OP_EQUAL
- | OP_EQUALVERIFY
- | OP_HASH160
- | OP_CHECKSIG
- | OP_CHECKMULTISIG
- | OP_PUBKEY PubKey
- | OP_INVALIDOPCODE Word8
- data PushDataType
- opPushData :: ByteString -> ScriptOp
- getScriptOps :: Get [ScriptOp]
- putScriptOps :: [ScriptOp] -> Put
- decodeScriptOps :: ByteString -> Either String Script
- encodeScriptOps :: Script -> ByteString
- data Tx = Tx {}
- txid :: Tx -> Hash256
- cbid :: CoinbaseTx -> Hash256
- data CoinbaseTx = CoinbaseTx {
- cbVersion :: !Word32
- cbPrevOutput :: !OutPoint
- cbData :: !ByteString
- cbInSequence :: !Word32
- cbOut :: ![TxOut]
- cbLockTime :: !Word32
- data TxIn = TxIn {
- prevOutput :: !OutPoint
- scriptInput :: !Script
- txInSequence :: !Word32
- data TxOut = TxOut {
- outValue :: !Word64
- scriptOutput :: !Script
- data OutPoint = OutPoint {
- outPointHash :: !Hash256
- outPointIndex :: !Word32
- encodeTxid :: Hash256 -> String
- decodeTxid :: String -> Maybe Hash256
- data MerkleBlock = MerkleBlock {
- merkleHeader :: !BlockHeader
- merkleTotalTxns :: !Word32
- mHashes :: [Hash256]
- mFlags :: [Bool]
- data BloomFlags
- data BloomFilter = BloomFilter {
- bloomData :: Seq Word8
- bloomFull :: Bool
- bloomEmpty :: Bool
- bloomHashFuncs :: Word32
- bloomTweak :: Word32
- bloomFlags :: BloomFlags
- newtype FilterLoad = FilterLoad {}
- newtype FilterAdd = FilterAdd {}
- newtype VarInt = VarInt {
- getVarInt :: Word64
- newtype VarString = VarString {}
- data NetworkAddress = NetworkAddress {
- naServices :: !Word64
- naAddress :: !(Word64, Word64)
- naPort :: !Word16
- data Addr = Addr {
- addrList :: ![NetworkAddressTime]
- type NetworkAddressTime = (Word32, NetworkAddress)
- data Version = Version {
- version :: !Word32
- services :: !Word64
- timestamp :: !Word64
- addrRecv :: !NetworkAddress
- addrSend :: !NetworkAddress
- verNonce :: !Word64
- userAgent :: !VarString
- startHeight :: !Word32
- relay :: !Bool
- newtype Ping = Ping {
- pingNonce :: Word64
- newtype Pong = Pong {
- pongNonce :: Word64
- data Alert = Alert {}
- data Message
- = MVersion Version
- | MVerAck
- | MAddr Addr
- | MInv Inv
- | MGetData GetData
- | MNotFound NotFound
- | MGetBlocks GetBlocks
- | MGetHeaders GetHeaders
- | MTx Tx
- | MBlock Block
- | MHeaders Headers
- | MGetAddr
- | MFilterLoad FilterLoad
- | MFilterAdd FilterAdd
- | MFilterClear
- | MPing Ping
- | MPong Pong
- | MAlert Alert
- data MessageHeader = MessageHeader {
- headMagic :: !Word32
- headCmd :: !MessageCommand
- headPayloadSize :: !Word32
- headChecksum :: !CheckSum32
- data MessageCommand
- = MCVersion
- | MCVerAck
- | MCAddr
- | MCInv
- | MCGetData
- | MCNotFound
- | MCGetBlocks
- | MCGetHeaders
- | MCTx
- | MCBlock
- | MCHeaders
- | MCGetAddr
- | MCFilterLoad
- | MCFilterAdd
- | MCFilterClear
- | MCPing
- | MCPong
- | MCAlert
Blocks
Data type describing a block in the bitcoin protocol. Blocks are sent in
response to GetData
messages that are requesting information from a
block hash.
Block | |
|
type BlockLocator = [Hash256]Source
Data type representing a GetBlocks message request. It is used in the
bitcoin protocol to retrieve blocks from a peer by providing it a
BlockLocator
object. The BlockLocator
is a sparse list of block hashes
from the caller node with the purpose of informing the receiving node
about the state of the caller's blockchain. The receiver node will detect
a wrong branch in the caller's main chain and send the caller appropriate
Blocks
. The response to a GetBlocks
message is an Inv
message
containing the list of block hashes pertaining to the request.
GetBlocks | |
|
Block Headers
data BlockHeader Source
Data type recording information on a Block
. The hash of a block is
defined as the hash of this data structure. The block mining process
involves finding a partial hash collision by varying the nonce in the
BlockHeader
and/or additional randomness in the CoinbaseTx
of this
Block
. Variations in the CoinbaseTx
will result in different merkle
roots in the BlockHeader
.
BlockHeader | |
|
Eq BlockHeader | |
Read BlockHeader | |
Show BlockHeader | |
Binary BlockHeader |
data GetHeaders Source
Similar to the GetBlocks
message type but for retrieving block headers
only. The response to a GetHeaders
request is a Headers
message
containing a list of block headers pertaining to the request. A maximum of
2000 block headers can be returned. GetHeaders
is used by thin (SPV)
clients to exclude block contents when synchronizing the blockchain.
GetHeaders | |
|
Eq GetHeaders | |
Read GetHeaders | |
Show GetHeaders | |
Binary GetHeaders |
The Headers
type is used to return a list of block headers in
response to a GetHeaders
message.
Headers | |
|
type BlockHeaderCount = (BlockHeader, VarInt)Source
BlockHeader
type with a transaction count as VarInt
blockid :: BlockHeader -> Hash256Source
Compute the hash of a block header
Requesting data
The GetData
type is used to retrieve information on a specific object
(Block
or Tx
) identified by the objects hash. The payload of a GetData
request is a list of InvVector
which represent all the hashes for which a
node wants to request information. The response to a GetBlock
message
wille be either a Block
or a Tx
message depending on the type of the
object referenced by the hash. Usually, GetData
messages are sent after a
node receives an Inv
message to obtain information on unknown object
hashes.
GetData | |
|
Invectory vectors represent hashes identifying objects such as a Block
or a Tx
. They are sent inside messages to notify other peers about
new data or data they have requested.
Data type identifying the type of an inventory vector.
InvError | Error. Data containing this type can be ignored. |
InvTx | InvVector hash is related to a transaction |
InvBlock | InvVector hash is related to a block |
InvMerkleBlock | InvVector has is related to a merkle block |
A NotFound
message is returned as a response to a GetData
message
whe one of the requested objects could not be retrieved. This could happen,
for example, if a tranasaction was requested and was not available in the
memory pool of the receiving node.
NotFound | |
|
Scripts
More informations on scripts is available here: http://en.bitcoin.it/wiki/Script
Data type representing a transaction script. Scripts are defined as lists
of script operators ScriptOp
. Scripts are used to:
- Define the spending conditions in the output of a transaction
- Provide the spending signatures in the input of a transaction
Data type representing all of the operators allowed inside a Script
.
data PushDataType Source
Data type representing the type of an OP_PUSHDATA opcode.
OPCODE | The next opcode bytes is data to be pushed onto the stack |
OPDATA1 | The next byte contains the number of bytes to be pushed onto the stack |
OPDATA2 | The next two bytes contains the number of bytes to be pushed onto the stack |
OPDATA4 | The next four bytes contains the number of bytes to be pushed onto the stack |
Eq PushDataType | |
Read PushDataType | |
Show PushDataType |
opPushData :: ByteString -> ScriptOpSource
Optimally encode data using one of the 4 types of data pushing opcodes
putScriptOps :: [ScriptOp] -> PutSource
decodeScriptOps :: ByteString -> Either String ScriptSource
Decode a Script
from a ByteString by omiting the length of the script.
This is used to produce scripthash addresses.
encodeScriptOps :: Script -> ByteStringSource
Encode a Script
into a ByteString by omiting the length of the script.
This is used to produce scripthash addresses.
Transactions
Data type representing a bitcoin transaction
cbid :: CoinbaseTx -> Hash256Source
Computes the hash of a coinbase transaction.
data CoinbaseTx Source
Data type representing the coinbase transaction of a Block
. Coinbase
transactions are special types of transactions which are created by miners
when they find a new block. Coinbase transactions have no inputs. They have
outputs sending the newly generated bitcoins together with all the block's
fees to a bitcoin address (usually the miners address). Data can be embedded
in a Coinbase transaction which can be chosen by the miner of a block. This
data also typically contains some randomness which is used, together with
the nonce, to find a partial hash collision on the block's hash.
CoinbaseTx | |
|
Eq CoinbaseTx | |
Read CoinbaseTx | |
Show CoinbaseTx | |
Binary CoinbaseTx |
Data type representing a transaction input.
TxIn | |
|
Data type representing a transaction output.
TxOut | |
|
The OutPoint is used inside a transaction input to reference the previous transaction output that it is spending.
OutPoint | |
|
encodeTxid :: Hash256 -> StringSource
Encodes a transaction hash as little endian in HEX format. This is mostly used for displaying transaction ids. Internally, these ids are handled as big endian but are transformed to little endian when displaying them.
decodeTxid :: String -> Maybe Hash256Source
Decodes a little endian transaction hash in HEX format.
Merkle trees and bloom filters
data MerkleBlock Source
MerkleBlock | |
|
Eq MerkleBlock | |
Read MerkleBlock | |
Show MerkleBlock | |
Binary MerkleBlock |
Bloom Filter
data BloomFlags Source
The bloom flags are used to tell the remote peer how to auto-update the provided bloom filter.
BloomUpdateNone | Never update |
BloomUpdateAll | Auto-update on all outputs |
BloomUpdateP2PubKeyOnly | Only auto-update on outputs that are pay-to-pubkey or pay-to-multisig. This is the default setting. |
Eq BloomFlags | |
Read BloomFlags | |
Show BloomFlags | |
Binary BloomFlags |
data BloomFilter Source
A bloom filter is a probabilistic data structure that SPV clients send to other peers to filter the set of transactions received from them. Bloom filters are probabilistic and have a false positive rate. Some transactions that pass the filter may not be relevant to the receiving peer. By controlling the false positive rate, SPV nodes can trade off bandwidth versus privacy.
BloomFilter | |
|
Eq BloomFilter | |
Read BloomFilter | |
Show BloomFilter | |
Binary BloomFilter |
newtype FilterLoad Source
Set a new bloom filter on the peer connection.
Eq FilterLoad | |
Read FilterLoad | |
Show FilterLoad | |
Binary FilterLoad |
Add the given data element to the connections current filter without requiring a completely new one to be set.
Network types
Data type representing a variable length integer. The VarInt
type
usually precedes an array or a string that can vary in length.
Data type for variable length strings. Variable length strings are
serialized as a VarInt
followed by a bytestring.
data NetworkAddress Source
Data type describing a bitcoin network address. Addresses are stored in
IPv6. IPv4 addresses are mapped to IPv6 using IPv4 mapped IPv6 addresses:
http://en.wikipedia.org/wiki/IPv6#IPv4-mapped_IPv6_addresses. Sometimes,
timestamps are sent together with the NetworkAddress
such as in the Addr
data type.
NetworkAddress | |
|
Eq NetworkAddress | |
Read NetworkAddress | |
Show NetworkAddress | |
Binary NetworkAddress |
Provides information on known nodes in the bitcoin network. An Addr
type is sent inside a Message
as a response to a GetAddr
message.
Addr | |
|
type NetworkAddressTime = (Word32, NetworkAddress)Source
Network address with a timestamp
When a bitcoin node creates an outgoing connection to another node,
the first message it will send is a Version
message. The other node
will similarly respond with it's own Version
message.
Version | |
|
A Ping message is sent to bitcoin peers to check if a TCP/IP connection is still valid.
A Pong message is sent as a response to a ping message.
Data type describing signed messages that can be sent between bitcoin nodes to display important notifications to end users about the health of the network.
Alert | |
|
Messages
The Message
type is used to identify all the valid messages that can be
sent between bitcoin peers. Only values of type Message
will be accepted
by other bitcoin peers as bitcoin protocol messages need to be correctly
serialized with message headers. Serializing a Message
value will
include the MessageHeader
with the correct checksum value automatically.
No need to add the MessageHeader
separately.
data MessageHeader Source
Data type representing the header of a Message
. All messages sent between
nodes contain a message header.
MessageHeader | |
|
Eq MessageHeader | |
Read MessageHeader | |
Show MessageHeader | |
Binary MessageHeader |
data MessageCommand Source
A MessageCommand
is included in a MessageHeader
in order to identify
the type of message present in the payload. This allows the message
de-serialization code to know how to decode a particular message payload.
Every valid Message
constructor has a corresponding MessageCommand
constructor.
MCVersion | |
MCVerAck | |
MCAddr | |
MCInv | |
MCGetData | |
MCNotFound | |
MCGetBlocks | |
MCGetHeaders | |
MCTx | |
MCBlock | |
MCHeaders | |
MCGetAddr | |
MCFilterLoad | |
MCFilterAdd | |
MCFilterClear | |
MCPing | |
MCPong | |
MCAlert |
Eq MessageCommand | |
Read MessageCommand | |
Show MessageCommand | |
Binary MessageCommand |