block
— All things Block related¶
This module contains the famous Block class (and subcomponents) as well as payloads to request block data from the network.
Block and subcomponents¶
A Block is a data structure pertaining to the NEO network containing transactions that are permanently recorded. Its arguably most important content are the transactions which modify the state of the chain (e.g. token balance updates) or execute a smart contract of which the execution result is recorded.
-
class
neo3.network.payloads.block.
Block
(header, transactions=None, *args, **kwargs)¶ Bases:
neo3.network.payloads.inventory.IInventory
The famous Block. I transfer chain state.
-
deserialize
(reader)¶ Deserialize the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Raises
ValueError – if the content count of the block is zero, or if there is a duplicate transaction in the list, or if the merkle root does not included the calculated root.
- Return type
-
classmethod
deserialize_from_bytes
(data)¶ Parse data into an object instance.
-
get_hash_data
(protocol_magic)¶ Get the unsigned data
-
get_script_hashes_for_verifying
(snapshot)¶ Helper method to get the data used in verifying the object.
-
serialize
(writer)¶ Serialize the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-
serialize_unsigned
(writer)¶ Serialize the unsigned part of the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-
trim
()¶ Reduce a block in size by replacing the transaction objects with their identifying hashes.
- Return type
-
property
inventory_type
¶ Inventory type identifier.
- Return type
-
property
next_consensus
¶ The hash of the consensus node that will generate the next block
- Return type
-
property
primary_index
¶ The index into the consensus node list that was used to generate this block
- Return type
-
-
class
neo3.network.payloads.block.
TrimmedBlock
(header, hashes)¶ Bases:
neo3.core.serialization.ISerializable
A size reduced Block instance.
Contains consensus data and transactions hashes instead of their full objects.
-
deserialize
(reader)¶ Deserialize the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Return type
-
classmethod
deserialize_from_bytes
(data)¶ Parse data into an object instance.
-
hash
()¶ A unique identifier based on the unsigned data portion of the object
-
serialize
(writer)¶ Serialize the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-
property
index
¶ The height of the block
-
-
class
neo3.network.payloads.block.
Header
(version, prev_hash, timestamp, index, primary_index, next_consensus, witness, merkle_root=None, *args, **kwargs)¶ Bases:
neo3.network.payloads.verification.IVerifiable
A Block header only object.
Does not contain any consensus data or transactions.
See also
-
deserialize
(reader)¶ Deserialize the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Raises
ValueError – if the check byte does not equal.
- Return type
-
classmethod
deserialize_from_bytes
(data)¶ Parse data into an object instance.
-
deserialize_unsigned
(reader)¶ Deserialize the unsigned data part of the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Raises
ValueError – if the primary_index field is greater than the configured consensus validator count.
- Return type
-
get_hash_data
(protocol_magic)¶ Get the unsigned data
-
get_script_hashes_for_verifying
(snapshot)¶ Helper method to get the data used in verifying the object.
-
hash
()¶ Get a unique identifier based on the unsigned data portion of the object.
- Return type
-
serialize
(writer)¶ Serialize the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-
Payloads¶
There are four payloads discussed in this section. Two for requesting data and two for replying to such requests.
Requesting¶
The GetBlocksPayload
and GetBlockByIndexPayload
are used to request Block data (including block Headers). Use these in conjunction with the GETBLOCKS
and GETBLOCKBYINDEX
or GETHEADERS
message types.
The GetBlocksPayload is used in the classic Bitcoin like data exchange structure in which you request a list of hashes first, then request the actual Block data using the hash list. This gives the flexibility to request a series of Block data which are non-consecutive in a single request.
The GetBlockByIndexPayload is a payload new to NEO3 with which you can directly request the full Block using a block height and a count. This is a simplified interface compared to using the GetBlocksPayload but is limited to consecutive data in a single request.
The GetBlocksByIndexPayload is also used as for requesting headers via the GETHEADERS
message type.
Responding¶
The HeadersPayload
is used to reply to a HEADERS
type message and returns Header
objects.
The MerkleBlockPayload
is used to reply to a GETDATA
or GETBLOCKDATA
type message under the specific condition that a bloomfilter has been loaded (TODO: add ref to filter). Responding to the aforementioned message types under the condition that no bloomfilter is present is respectively done via an INV
type message with an InventoryPayload or a BLOCK
type message where the Block object is the message payload.
-
class
neo3.network.payloads.block.
GetBlocksPayload
(hash_start, count=- 1)¶ Bases:
neo3.core.serialization.ISerializable
Used to request an array block hashes that can be retrieved via a message with the
GETDATA
type.Create payload.
- Parameters
hash_start (
UInt256
) –starting point from which to return the next hash.
Note
For syncing supply the local best height block hash to receive the hashes in the range of best_height+1 to best_height+1+count
count – number of hashes to return.
-
deserialize
(reader)¶ Deserialize the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Return type
-
classmethod
deserialize_from_bytes
(data)¶ Parse data into an object instance.
-
serialize
(writer)¶ Serialize the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-
class
neo3.network.payloads.block.
GetBlockByIndexPayload
(index_start, count=2000)¶ Bases:
neo3.core.serialization.ISerializable
Used to request full Block or Header objects via a message with the
GETBLOCKBYINDEX
orGETHEADERS
type respectively.Create payload.
- Parameters
-
deserialize
(reader)¶ Deserialize the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Raises
ValueError – if count is zero or exceeds
MAX_BLOCKS_COUNT
.- Return type
-
classmethod
deserialize_from_bytes
(data)¶ Parse data into an object instance.
-
serialize
(writer)¶ Serialize the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-
class
neo3.network.payloads.block.
HeadersPayload
(headers=None)¶ Bases:
neo3.core.serialization.ISerializable
Should not be called directly. Use create() instead.
-
deserialize
(reader)¶ Deserialize the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Return type
-
classmethod
deserialize_from_bytes
(data)¶ Parse data into an object instance.
-
serialize
(writer)¶ Serialize the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-
MAX_HEADERS_COUNT
= 2000¶
-
-
class
neo3.network.payloads.block.
MerkleBlockPayload
(block, flags)¶ Bases:
neo3.core.serialization.ISerializable
-
deserialize
(reader)¶ Deserialize the object from a binary stream.
- Parameters
reader (
BinaryReader
) – instance.- Return type
-
classmethod
deserialize_from_bytes
(data)¶ Parse data into an object instance.
-
serialize
(writer)¶ Serialize the object into a binary stream.
- Parameters
writer (
BinaryWriter
) – instance.- Return type
-