refactor(algod-client): restructure block models to align with JS SDK

Align Python block model structure with the JavaScript SDK and OpenAPI
spec for cross-SDK consistency.
Structural changes:
- Rename GetBlock -> BlockResponse (matches OAS spec + JS/TS SDKs)
- Add TxnCommitments nested type for transaction roots (txn, txn256)
- Add RewardState nested type for reward fields (fees, rwd, earn, etc.)
- Add UpgradeState nested type for protocol upgrade state
- Add UpgradeVote nested type for upgrade vote parameters
- Refactor BlockHeader to use flattened nested types
- Change BlockEvalDelta.bytes -> bytes_value (avoid Python keyword)
- Fix inner_txns type: SignedTxnInBlock -> SignedTxnWithAD
- Make previous_block_hash and genesis_hash non-optional with defaults
- Fix get_block() to return BlockResponse (typed) instead of Block
- Export typed BlockResponse from _block.py instead of untyped version
BREAKING CHANGE:
- GetBlock removed, use BlockResponse instead
- Field access patterns changed in BlockHeader:
  - header.fee_sink -> header.reward_state.fee_sink
  - header.current_protocol -> header.upgrade_state.current_protocol
  - header.upgrade_propose -> header.upgrade_vote.upgrade_propose
  - header.transactions_root -> header.txn_commitments.transactions_root
- Block response structure: result.header -> result.block.header

Author: aorumbayev

api/oas-generator/src/oas_generator/builder.py

@@ -936,11 +936,11 @@ def _build_response(self, responses: dict[str, Any], operation_id: str) -> ctx.R
             self.uses_block_models = True
             media_types = media_types or ["application/json"]
             return ctx.ResponseDescriptor(
-                type_hint="models.GetBlock",
+                type_hint="models.BlockResponse",
                 media_types=media_types,
                 description=payload.get("description"),
                 is_binary=False,
-                model="GetBlock",
+                model="BlockResponse",
             )
         if schema is None:
             return None

api/oas-generator/src/oas_generator/renderer/engine.py

@@ -17,18 +17,12 @@
 
 class TemplateRenderer:
     BLOCK_MODEL_EXPORTS: ClassVar[list[str]] = [
-        "ApplyData",
-        "BlockEvalDelta",
-        "BlockStateDelta",
-        "BlockAccountStateDelta",
-        "BlockAppEvalDelta",
-        "BlockStateProofTrackingData",
         "BlockStateProofTracking",
         "ParticipationUpdates",
         "SignedTxnInBlock",
         "BlockHeader",
         "Block",
-        "GetBlock",
+        "BlockResponse",
     ]
     LEDGER_STATE_DELTA_EXPORTS: ClassVar[list[str]] = [
         "LedgerTealValue",

api/oas-generator/src/oas_generator/renderer/templates/models/block.py.j2

@@ -26,13 +26,17 @@ __all__ = [
     "BlockAppEvalDelta",
     "BlockStateProofTrackingData",
     "BlockStateProofTracking",
+    "TxnCommitments",
+    "RewardState",
+    "UpgradeState",
+    "UpgradeVote",
     "ParticipationUpdates",
     "ApplyData",
     "SignedTxnWithAD",
     "SignedTxnInBlock",
     "BlockHeader",
     "Block",
-    "GetBlock",
+    "BlockResponse",
 ]
 
 
@@ -118,7 +122,7 @@ class BlockEvalDelta:
     """Represents a TEAL value delta within block state changes."""
 
     action: int = field(metadata=wire("at", required=True))
-    bytes: str | None = field(default=None, metadata=wire("bs"))
+    bytes_value: bytes | None = field(default=None, metadata=wire("bs"))
     uint: int | None = field(default=None, metadata=wire("ui"))
 
 
@@ -179,6 +183,46 @@ class SignedTxnWithAD:
     apply_data: ApplyData | None = field(default=None, metadata=flatten(lambda: ApplyData))
 
 
+@dataclass(slots=True)
+class TxnCommitments:
+    """Transaction commitment hashes for the block."""
+
+    transactions_root: bytes = field(default_factory=lambda: bytes(32), metadata=wire("txn"))
+    transactions_root_sha256: bytes = field(default_factory=lambda: bytes(32), metadata=wire("txn256"))
+
+
+@dataclass(slots=True)
+class RewardState:
+    """Reward distribution state for the block."""
+
+    fee_sink: str | None = field(default=None, metadata=addr("fees"))
+    rewards_pool: str | None = field(default=None, metadata=addr("rwd"))
+    rewards_level: int | None = field(default=None, metadata=wire("earn"))
+    rewards_rate: int | None = field(default=None, metadata=wire("rate"))
+    rewards_residue: int | None = field(default=None, metadata=wire("frac"))
+    rewards_recalculation_round: int | None = field(default=None, metadata=wire("rwcalr"))
+
+
+@dataclass(slots=True)
+class UpgradeState:
+    """Protocol upgrade state for the block."""
+
+    current_protocol: str | None = field(default=None, metadata=wire("proto"))
+    next_protocol: str | None = field(default=None, metadata=wire("nextproto"))
+    next_protocol_approvals: int | None = field(default=None, metadata=wire("nextyes"))
+    next_protocol_vote_before: int | None = field(default=None, metadata=wire("nextbefore"))
+    next_protocol_switch_on: int | None = field(default=None, metadata=wire("nextswitch"))
+
+
+@dataclass(slots=True)
+class UpgradeVote:
+    """Protocol upgrade vote parameters for the block."""
+
+    upgrade_propose: str | None = field(default=None, metadata=wire("upgradeprop"))
+    upgrade_delay: int | None = field(default=None, metadata=wire("upgradedelay"))
+    upgrade_approve: bool | None = field(default=None, metadata=wire("upgradeyes"))
+
+
 @dataclass(slots=True)
 class ParticipationUpdates:
     """Participation account updates embedded in a block."""
@@ -216,12 +260,12 @@ class BlockAppEvalDelta:
             decode=_decode_local_deltas,
         ),
     )
-    inner_txns: list[SignedTxnInBlock] | None = field(
+    inner_txns: list[SignedTxnWithAD] | None = field(
         default=None,
         metadata=wire(
             "itx",
             encode=encode_model_sequence,
-            decode=lambda raw: decode_model_sequence(lambda: SignedTxnInBlock, raw),
+            decode=lambda raw: decode_model_sequence(lambda: SignedTxnWithAD, raw),
         ),
     )
     shared_accounts: tuple[str, ...] | None = field(default=None, metadata=addr_seq("sa"))
@@ -232,34 +276,34 @@ class BlockAppEvalDelta:
 class BlockHeader:
     """Block header fields."""
 
-    transactions_root: bytes = field(metadata=wire("txn", required=True))
     round: int | None = field(default=None, metadata=wire("rnd"))
-    previous_block_hash: bytes | None = field(default=None, metadata=wire("prev"))
+    txn_commitments: TxnCommitments = field(
+        default_factory=TxnCommitments,
+        metadata=flatten(lambda: TxnCommitments),
+    )
+    previous_block_hash: bytes = field(default_factory=lambda: bytes(32), metadata=wire("prev"))
     previous_block_hash_512: bytes | None = field(default=None, metadata=wire("prev512"))
     seed: bytes | None = field(default=None, metadata=wire("seed"))
-    transactions_root_sha256: bytes | None = field(default=None, metadata=wire("txn256"))
     transactions_root_sha512: bytes | None = field(default=None, metadata=wire("txn512"))
     timestamp: int | None = field(default=None, metadata=wire("ts"))
     genesis_id: str | None = field(default=None, metadata=wire("gen"))
-    genesis_hash: bytes | None = field(default=None, metadata=wire("gh"))
+    genesis_hash: bytes = field(default_factory=lambda: bytes(32), metadata=wire("gh"))
     proposer: str | None = field(default=None, metadata=addr("prp"))
     fees_collected: int | None = field(default=None, metadata=wire("fc"))
     bonus: int | None = field(default=None, metadata=wire("bi"))
     proposer_payout: int | None = field(default=None, metadata=wire("pp"))
-    fee_sink: str | None = field(default=None, metadata=addr("fees"))
-    rewards_pool: str | None = field(default=None, metadata=addr("rwd"))
-    rewards_level: int | None = field(default=None, metadata=wire("earn"))
-    rewards_rate: int | None = field(default=None, metadata=wire("rate"))
-    rewards_residue: int | None = field(default=None, metadata=wire("frac"))
-    rewards_recalculation_round: int | None = field(default=None, metadata=wire("rwcalr"))
-    current_protocol: str | None = field(default=None, metadata=wire("proto"))
-    next_protocol: str | None = field(default=None, metadata=wire("nextproto"))
-    next_protocol_approvals: int | None = field(default=None, metadata=wire("nextyes"))
-    next_protocol_vote_before: int | None = field(default=None, metadata=wire("nextbefore"))
-    next_protocol_switch_on: int | None = field(default=None, metadata=wire("nextswitch"))
-    upgrade_propose: str | None = field(default=None, metadata=wire("upgradeprop"))
-    upgrade_delay: int | None = field(default=None, metadata=wire("upgradedelay"))
-    upgrade_approve: bool | None = field(default=None, metadata=wire("upgradeyes"))
+    reward_state: RewardState = field(
+        default_factory=RewardState,
+        metadata=flatten(lambda: RewardState),
+    )
+    upgrade_state: UpgradeState = field(
+        default_factory=UpgradeState,
+        metadata=flatten(lambda: UpgradeState),
+    )
+    upgrade_vote: UpgradeVote = field(
+        default_factory=UpgradeVote,
+        metadata=flatten(lambda: UpgradeVote),
+    )
     txn_counter: int | None = field(default=None, metadata=wire("tc"))
     state_proof_tracking: BlockStateProofTracking | None = field(
         default=None,
@@ -294,7 +338,7 @@ class Block:
 
 
 @dataclass(slots=True)
-class GetBlock:
+class BlockResponse:
     """Response payload for the get block endpoint (with optional certificate)."""
 
     block: Block = field(metadata=nested("block", lambda: Block))

src/algokit_algod_client/client.py

@@ -455,7 +455,7 @@ def get_block(
         round_: int,
         *,
         header_only: bool | None = None,
-    ) -> models.GetBlock:
+    ) -> models.BlockResponse:
         """
         Get the block for the given round.
         """
@@ -483,7 +483,7 @@ def get_block(
 
         response = self._request_with_retry(request_kwargs)
         if response.is_success:
-            return self._decode_response(response, model=models.GetBlock)
+            return self._decode_response(response, model=models.BlockResponse)
 
         raise UnexpectedStatusError(response.status_code, response.text)
 

src/algokit_algod_client/models/__init__.py

@@ -30,15 +30,18 @@
     BlockAppEvalDelta,
     BlockEvalDelta,
     BlockHeader,
+    BlockResponse,
     BlockStateDelta,
     BlockStateProofTracking,
     BlockStateProofTrackingData,
-    GetBlock,
     ParticipationUpdates,
+    RewardState,
     SignedTxnInBlock,
+    TxnCommitments,
+    UpgradeState,
+    UpgradeVote,
 )
 from ._block_hash_response import BlockHashResponse
-from ._block_response import BlockResponse
 from ._block_txids_response import BlockTxidsResponse
 from ._box import Box
 from ._box_descriptor import BoxDescriptor
@@ -155,7 +158,6 @@
     "EvalDelta",
     "EvalDeltaKeyValue",
     "GenesisFileInJson",
-    "GetBlock",
     "GetBlockTimeStampOffsetResponse",
     "GetSyncRoundResponse",
     "GetTransactionGroupLedgerStateDeltasForRound",
@@ -191,6 +193,7 @@
     "PendingTransactionResponse",
     "PendingTransactionsResponse",
     "PostTransactionsResponse",
+    "RewardState",
     "ScratchChange",
     "SignedTransaction",
     "SignedTxnInBlock",
@@ -217,5 +220,8 @@
     "TransactionGroupLedgerStateDeltasForRoundResponse",
     "TransactionParametersResponse",
     "TransactionProof",
+    "TxnCommitments",
+    "UpgradeState",
+    "UpgradeVote",
     "VersionContainsTheCurrentAlgodVersion",
 ]