python: block types and wrapper

bindings/python/examples/client/08_data_block.py

@@ -3,7 +3,7 @@
 import os
 from dataclasses import asdict
 from dotenv import load_dotenv
-from iota_sdk import Client, utf8_to_hex, hex_to_utf8, TaggedDataPayload
+from iota_sdk import BasicBlock, Client, utf8_to_hex, hex_to_utf8, TaggedDataPayload
 
 load_dotenv()
 
@@ -13,17 +13,21 @@
 client = Client(nodes=[node_url])
 
 # Create and post a block with a tagged data payload
-block = client.submit_payload(
+block_id = client.submit_payload(
     TaggedDataPayload(
         utf8_to_hex("tag"),
-        utf8_to_hex("data")))
+        utf8_to_hex("data")))[0]
 
-print(f'Data block sent: {os.environ["EXPLORER_URL"]}/block/{block[0]}')
+print(f'Data block sent: {os.environ["EXPLORER_URL"]}/block/{block_id}')
 
-block = client.get_block_data(block[0])
-print(f'Block data: {json.dumps(asdict(block), indent=4)}')
+block = client.get_block_data(block_id).block
 
-payload = block.payload
+if isinstance(block, BasicBlock):
+    print(f'Block data: {json.dumps(asdict(block), indent=4)}')
 
-if payload and 'data' in payload and payload['data']:
-    print(f'Decoded data: { hex_to_utf8(payload["data"]) }')
+    payload = block.payload
+
+    if payload and 'data' in payload and payload['data']:
+        print(f'Decoded data: { hex_to_utf8(payload["data"]) }')
+else:
+    raise ValueError("block must be an instance of BasicBlock")

bindings/python/examples/client/submit_and_read_block.py

@@ -11,7 +11,7 @@
 # Make sure you have first installed it with `pip install iota_sdk`
 import os
 from dotenv import load_dotenv
-from iota_sdk import Client, hex_to_utf8, utf8_to_hex, TaggedDataPayload
+from iota_sdk import BasicBlock, Client, hex_to_utf8, utf8_to_hex, TaggedDataPayload
 
 load_dotenv()
 
@@ -82,15 +82,18 @@
 metadata = client.get_block_metadata(block_id)
 
 # Get the whole block
-block = client.get_block_data(block_id)
-payload_out = block.payload
-tag_hex_out = block.payload.tag
-message_hex_out = block.payload.data
-
-# Unpackage the payload (from hex to text)
-message_out = hex_to_utf8(message_hex_out)
-print('\nYour message, read from the Shimmer network:')
-print(f'  {message_out}')
+block = client.get_block_data(block_id).block
+if isinstance(block, BasicBlock):
+    payload_out = block.payload
+    tag_hex_out = block.payload.tag
+    message_hex_out = block.payload.data
+
+    # Unpackage the payload (from hex to text)
+    message_out = hex_to_utf8(message_hex_out)
+    print('\nYour message, read from the Shimmer network:')
+    print(f'  {message_out}')
+else:
+    raise ValueError("block must be an instance of BasicBlock")
 
 # Or see the message online, with the testnet explorer.
 print(

bindings/python/iota_sdk/__init__.py

@@ -12,7 +12,10 @@
 from .prefix_hex import *
 from .types.address import *
 from .types.balance import *
-from .types.block import *
+from .types.block.basic import *
+from .types.block.block import *
+from .types.block.wrapper import *
+from .types.block.validation import *
 from .types.block_builder_options import *
 from .types.burn import *
 from .types.client_options import *

bindings/python/iota_sdk/client/_high_level_api.py

@@ -4,7 +4,7 @@
 from typing import List, Optional
 from dataclasses import dataclass
 from abc import ABCMeta, abstractmethod
-from iota_sdk.types.block import Block
+from iota_sdk.types.block.wrapper import BlockWrapper
 from iota_sdk.types.common import CoinType, HexStr, json
 from iota_sdk.types.output import OutputWithMetadata
 from iota_sdk.types.output_id import OutputId
@@ -94,7 +94,7 @@ def get_outputs_ignore_errors(
         })
         return [OutputWithMetadata.from_dict(o) for o in outputs]
 
-    def find_blocks(self, block_ids: List[HexStr]) -> List[Block]:
+    def find_blocks(self, block_ids: List[HexStr]) -> List[BlockWrapper]:
         """Find all blocks by provided block IDs.
 
         Args:
@@ -106,7 +106,7 @@ def find_blocks(self, block_ids: List[HexStr]) -> List[Block]:
         blocks = self._call_method('findBlocks', {
             'blockIds': block_ids
         })
-        return [Block.from_dict(block) for block in blocks]
+        return [BlockWrapper.from_dict(block) for block in blocks]
 
     def find_inputs(self, addresses: List[str], amount: int):
         """Function to find inputs from addresses for a provided amount(useful for offline signing).

bindings/python/iota_sdk/client/_node_core_api.py

@@ -5,7 +5,8 @@
 from abc import ABCMeta, abstractmethod
 from dacite import from_dict
 
-from iota_sdk.types.block import Block, BlockMetadata
+from iota_sdk.types.block.wrapper import BlockWrapper
+from iota_sdk.types.block.block import BlockMetadata
 from iota_sdk.types.common import HexStr
 from iota_sdk.types.node_info import NodeInfo, NodeInfoWrapper
 from iota_sdk.types.output import OutputWithMetadata, OutputMetadata
@@ -57,7 +58,7 @@ def get_tips(self) -> List[HexStr]:
         """
         return self._call_method('getTips')
 
-    def post_block(self, block: Block) -> HexStr:
+    def post_block(self, block: BlockWrapper) -> HexStr:
         """Post a block.
 
         Args:
@@ -70,10 +71,10 @@ def post_block(self, block: Block) -> HexStr:
             'block': block.__dict__
         })
 
-    def get_block_data(self, block_id: HexStr) -> Block:
+    def get_block_data(self, block_id: HexStr) -> BlockWrapper:
         """Get the block corresponding to the given block id.
         """
-        return Block.from_dict(self._call_method('getBlock', {
+        return BlockWrapper.from_dict(self._call_method('getBlock', {
             'blockId': block_id
         }))
 
@@ -127,13 +128,13 @@ def get_output_metadata(
             'outputId': output_id_str
         }))
 
-    def get_included_block(self, transaction_id: HexStr) -> Block:
+    def get_included_block(self, transaction_id: HexStr) -> BlockWrapper:
         """Returns the included block of the given transaction.
 
         Returns:
             The included block.
         """
-        return Block.from_dict(self._call_method('getIncludedBlock', {
+        return BlockWrapper.from_dict(self._call_method('getIncludedBlock', {
             'transactionId': transaction_id
         }))
 

bindings/python/iota_sdk/client/client.py

@@ -13,7 +13,7 @@
 from iota_sdk.client._high_level_api import HighLevelAPI
 from iota_sdk.client._utils import ClientUtils
 from iota_sdk.secret_manager.secret_manager import LedgerNanoSecretManager, MnemonicSecretManager, StrongholdSecretManager, SeedSecretManager
-from iota_sdk.types.block import Block
+from iota_sdk.types.block.wrapper import BlockWrapper
 from iota_sdk.types.common import HexStr, Node
 from iota_sdk.types.feature import Feature
 from iota_sdk.types.native_token import NativeToken
@@ -394,7 +394,8 @@ def sign_transaction(
             'preparedTransactionData': prepared_transaction_data
         }))
 
-    def submit_payload(self, payload: Payload) -> List[Union[HexStr, Block]]:
+    def submit_payload(
+            self, payload: Payload) -> List[Union[HexStr, BlockWrapper]]:
         """Submit a payload in a block.
 
         Args:
@@ -406,7 +407,7 @@ def submit_payload(self, payload: Payload) -> List[Union[HexStr, Block]]:
         result = self._call_method('postBlockPayload', {
             'payload': payload.to_dict()
         })
-        result[1] = Block.from_dict(result[1])
+        result[1] = BlockWrapper.from_dict(result[1])
         return result
 
     def listen_mqtt(self, topics: List[str], handler):

bindings/python/iota_sdk/types/block/basic.py

@@ -0,0 +1,46 @@
+# Copyright 2023 IOTA Stiftung
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Union
+from dacite import from_dict
+from iota_sdk.types.block.block import Block, BlockType
+from iota_sdk.types.common import HexStr, json
+from iota_sdk.types.payload import TaggedDataPayload, TransactionPayload
+
+
+@json
+@dataclass
+class BasicBlock(Block):
+    """A `BasicBlock` is the most common type of block used to issue various kinds of payloads such as transactions
+    at the cost of burning Mana.
+
+    Attributes:
+        strong_parents: Blocks that are strongly directly approved.
+        weak_parents: Blocks that are weakly directly approved.
+        shallow_like_parents: Blocks that are directly referenced to adjust opinion.
+        payload: The optional payload of this block.
+        burned_mana: The amount of Mana the Account identified by the IssuerId is at most willing to burn for this block.
+    """
+    strong_parents: List[HexStr]
+    weak_parents: List[HexStr]
+    shallow_like_parents: List[HexStr]
+    payload: Optional[Union[TaggedDataPayload,
+                      TransactionPayload]] = None
+    burned_mana: str
+    type: int = field(
+        default_factory=lambda: BlockType.Basic,
+        init=False)
+
+    @classmethod
+    def from_dict(cls, basic_block_dict: Dict) -> BasicBlock:
+        """
+        The function `from_dict` takes a dictionary that contains the data needed to
+        create an instance of the `BasicBlock` class .
+
+        Returns:
+
+        An instance of the `BasicBlock` class .
+        """
+        return from_dict(BasicBlock, basic_block_dict)

bindings/python/iota_sdk/types/block.py → bindings/python/iota_sdk/types/block/block.py

@@ -2,53 +2,60 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from __future__ import annotations
-from enum import Enum
+from enum import Enum, IntEnum
 from dataclasses import dataclass
-from typing import List, Optional, Union, Dict
-from dacite import from_dict
+from typing import List, Optional
 from iota_sdk.types.common import HexStr, json
-from iota_sdk.types.payload import TaggedDataPayload, TransactionPayload
-from iota_sdk.utils import Utils
+
+
+class BlockType(IntEnum):
+    """Block types.
+
+    Attributes:
+        Basic (0): A Basic Block.
+        Validation (1): A Validation Block.
+    """
+    Basic = 0
+    Validation = 1
 
 
 @json
 @dataclass
 class Block:
-    """Represent the object that nodes gossip around the network.
+    """Base class for blocks.
+    """
+    type: int
+
+
+@json
+@dataclass
+class BlockMetadata:
+    """Block Metadata.
 
     Attributes:
-        protocol_version: The protocol version with which this block was issued.
+        block_id: The id of the block.
         strong_parents: Blocks that are strongly directly approved.
         weak_parents: Blocks that are weakly directly approved.
         shallow_like_parents: Blocks that are directly referenced to adjust opinion.
-        burned_mana: The amount of Mana the Account identified by the IssuerId is at most willing to burn for this block.
-        payload: The optional payload of this block.
+        is_solid: Whether the block is solid.
+        referenced_by_milestone_index: The milestone index referencing the block.
+        milestone_index: The milestone index if the block contains a milestone payload.
+        ledger_inclusion_state: The ledger inclusion state of the block.
+        conflict_reason: The optional conflict reason of the block.
+        should_promote: Whether the block should be promoted.
+        should_reattach: Whether the block should be reattached.
     """
-
-    protocol_version: int
+    block_id: HexStr
     strong_parents: List[HexStr]
     weak_parents: List[HexStr]
     shallow_like_parents: List[HexStr]
-    burned_mana: str
-    payload: Optional[Union[TaggedDataPayload,
-                      TransactionPayload]] = None
-
-    @classmethod
-    def from_dict(cls, block_dict: Dict) -> Block:
-        """
-        The function `from_dict` takes a dictionary that contains the data needed to
-        create an instance of the `Block` class.
-
-        Returns:
-
-        An instance of the `Block` class.
-        """
-        return from_dict(Block, block_dict)
-
-    def id(self) -> HexStr:
-        """Rreturns the block ID as a hexadecimal string.
-        """
-        return Utils.block_id(self)
+    is_solid: bool
+    referenced_by_milestone_index: Optional[int] = None
+    milestone_index: Optional[int] = None
+    ledger_inclusion_state: Optional[LedgerInclusionState] = None
+    conflict_reason: Optional[TransactionFailureReason] = None
+    should_promote: Optional[bool] = None
+    should_reattach: Optional[bool] = None
 
 
 class LedgerInclusionState(str, Enum):
@@ -139,34 +146,3 @@ def __str__(self):
             21: "Failed to claim delegation reward.",
             255: "The semantic validation failed for a reason not covered by the previous variants."
         }[self.value]
-
-
-@json
-@dataclass
-class BlockMetadata:
-    """Block Metadata.
-
-    Attributes:
-        block_id: The id of the block.
-        strong_parents: Blocks that are strongly directly approved.
-        weak_parents: Blocks that are weakly directly approved.
-        shallow_like_parents: Blocks that are directly referenced to adjust opinion.
-        is_solid: Whether the block is solid.
-        referenced_by_milestone_index: The milestone index referencing the block.
-        milestone_index: The milestone index if the block contains a milestone payload.
-        ledger_inclusion_state: The ledger inclusion state of the block.
-        conflict_reason: The optional conflict reason of the block.
-        should_promote: Whether the block should be promoted.
-        should_reattach: Whether the block should be reattached.
-    """
-    block_id: HexStr
-    strong_parents: List[HexStr]
-    weak_parents: List[HexStr]
-    shallow_like_parents: List[HexStr]
-    is_solid: bool
-    referenced_by_milestone_index: Optional[int] = None
-    milestone_index: Optional[int] = None
-    ledger_inclusion_state: Optional[LedgerInclusionState] = None
-    conflict_reason: Optional[TransactionFailureReason] = None
-    should_promote: Optional[bool] = None
-    should_reattach: Optional[bool] = None