feat: x-algokit-byte-length support and block model restructuring for cross-SDK alignment (#242)

* feat: add x-algokit-byte-length vendor extension support for fixed-length byte validation

- Add byte_length and list_inner_byte_length fields to TypeInfo in builder.py
- Update _build_metadata() to generate fixed-length byte serde helpers
- Add encode_fixed_bytes_base64/decode_fixed_bytes_base64 helpers for 32/64 byte validation
- Add encode_fixed_bytes_sequence/decode_fixed_bytes_sequence for array validation
- Regenerate API clients with fixed-length byte fields (group, lease, signature, etc.)
- Update OAS_BRANCH to fix/byte-len-validation for spec generation

* 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

* refactor: excludes block models from generated code

Excludes block models from the generated client code to allow separate handling.

This change introduces a mechanism to conditionally include block models during code generation based on a client configuration. It also updates the AVM debugger source map generation by incorporating hashes in the standard AVM debugger format.

Skips tests that depend on msgpack handling until mock server is fixed.

* fix(algod-client): restore block model types to public exports

Ensures all block-related types (ApplyData, BlockEvalDelta, BlockStateDelta,
SignedTxnWithAD, TxnCommitments, RewardState, UpgradeState, UpgradeVote, etc.)
remain publicly exported from algokit_algod_client.models for type hints,
isinstance checks, and IDE autocomplete. These types are returned by the public
API and must be accessible to users. Aligns with TypeScript SDK behavior.

Author: aorumbayev

.gitignore

@@ -184,3 +184,5 @@ api/specs/
 .polytest*/
 
 references/
+
+AGENTS.md

MIGRATION-NOTES.md

@@ -40,6 +40,73 @@ A collection of notes to consolidate todos during decoupling efforts (similar do
 
 - BoxReference used to be a subclass of algosdk BoxReference, now there is a direct equivalent imported from transact package. Do we want to keep aliasing the BoxReference to transact version or do we want to deprecate and advice consumers to import directly from transact?
 
+## Block Model Restructuring (TS Alignment)
+
+### Breaking Changes
+
+- `GetBlock` removed → use `BlockResponse`
+- `BlockHeader` fields reorganized into nested types:
+  - `header.fee_sink` → `header.reward_state.fee_sink`
+  - `header.rewards_pool` → `header.reward_state.rewards_pool`
+  - `header.rewards_level` → `header.reward_state.rewards_level`
+  - `header.rewards_rate` → `header.reward_state.rewards_rate`
+  - `header.rewards_residue` → `header.reward_state.rewards_residue`
+  - `header.rewards_recalculation_round` → `header.reward_state.rewards_recalculation_round`
+  - `header.current_protocol` → `header.upgrade_state.current_protocol`
+  - `header.next_protocol` → `header.upgrade_state.next_protocol`
+  - `header.next_protocol_approvals` → `header.upgrade_state.next_protocol_approvals`
+  - `header.next_protocol_vote_before` → `header.upgrade_state.next_protocol_vote_before`
+  - `header.next_protocol_switch_on` → `header.upgrade_state.next_protocol_switch_on`
+  - `header.upgrade_propose` → `header.upgrade_vote.upgrade_propose`
+  - `header.upgrade_delay` → `header.upgrade_vote.upgrade_delay`
+  - `header.upgrade_approve` → `header.upgrade_vote.upgrade_approve`
+  - `header.transactions_root` → `header.txn_commitments.transactions_root`
+  - `header.transactions_root_sha256` → `header.txn_commitments.transactions_root_sha256`
+- `BlockEvalDelta.bytes` → `BlockEvalDelta.bytes_value` (avoid Python keyword)
+- `BlockAppEvalDelta.inner_txns` type changed: `SignedTxnInBlock` → `SignedTxnWithAD`
+- `previous_block_hash` and `genesis_hash` now non-optional with `bytes(32)` defaults
+
+### Migration
+
+```python
+# Before
+from algokit_algod_client.models import GetBlock
+response: GetBlock = algod_client.get_block(...)
+fee_sink = response.block.header.fee_sink
+protocol = response.block.header.current_protocol
+proposal = response.block.header.upgrade_propose
+
+# After
+from algokit_algod_client.models import BlockResponse
+response: BlockResponse = algod_client.get_block(...)
+fee_sink = response.block.header.reward_state.fee_sink
+protocol = response.block.header.upgrade_state.current_protocol
+proposal = response.block.header.upgrade_vote.upgrade_propose
+```
+
+## Fixed-Length Byte Validation
+
+### Breaking Changes
+
+- Runtime validation for fixed-length byte fields (32/64 bytes)
+- `ValueError` raised if byte length doesn't match expected length
+- Affects: `group`, `lease`, signatures, hashes, keys, commitment roots
+
+### Migration
+
+```python
+# Validation now enforced at encode/decode
+# 32-byte fields: group, lease, transaction hashes, block hashes, keys
+# 64-byte fields: signatures, SHA-512 hashes
+
+# Before: silently accepted wrong lengths
+txn.group = bytes(10)  # No error
+
+# After: raises ValueError
+txn.group = bytes(10)  # ValueError: Expected 32 bytes, got 10
+txn.group = bytes(32)  # OK
+```
+
 ## Account and Signer Type Renames (TS Alignment)
 
 ### Breaking Changes

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

@@ -33,6 +33,8 @@ class TypeInfo:
     is_locals_reference: bool = False
     is_holding_reference: bool = False
     needs_datetime: bool = False
+    byte_length: int | None = None  # Fixed byte length from x-algokit-byte-length
+    list_inner_byte_length: int | None = None  # Fixed byte length for list items
     imports: set[str] = field(default_factory=set)
 
 
@@ -170,7 +172,10 @@ def resolve(self, schema: ctx.RawSchema, *, hint: str = "Inline") -> TypeInfo:
         if schema_type == "string":
             fmt = schema.get("format")
             if fmt in {"byte", "binary"} or schema.get("x-algokit-bytes-base64"):
-                info = TypeInfo(annotation="bytes", is_bytes=True)
+                # Extract fixed byte length if present
+                byte_length_val = schema.get("x-algokit-byte-length")
+                byte_length = int(byte_length_val) if byte_length_val is not None else None
+                info = TypeInfo(annotation="bytes", is_bytes=True, byte_length=byte_length)
             elif fmt == "date-time":
                 info = TypeInfo(
                     annotation="datetime",
@@ -219,6 +224,7 @@ def _resolve_array(self, schema: ctx.RawSchema, *, hint: str) -> TypeInfo:
             list_inner_model=inner.model,
             list_inner_enum=inner.enum,
             list_inner_is_bytes=inner.is_bytes,
+            list_inner_byte_length=inner.byte_length,
             is_signed_transaction=inner.is_signed_transaction,
             is_box_reference=inner.is_box_reference,
             is_locals_reference=inner.is_locals_reference,
@@ -462,6 +468,10 @@ def _build_model(self, entry: SchemaEntry) -> ctx.ModelDescriptor:  # noqa: C901
                 imports.add("from ._serde_helpers import decode_bytes_base64, encode_bytes_base64")
             if "encode_bytes_sequence" in field.metadata or "decode_bytes_sequence" in field.metadata:
                 imports.add("from ._serde_helpers import decode_bytes_sequence, encode_bytes_sequence")
+            if "encode_fixed_bytes_base64" in field.metadata or "decode_fixed_bytes_base64" in field.metadata:
+                imports.add("from ._serde_helpers import decode_fixed_bytes_base64, encode_fixed_bytes_base64")
+            if "encode_fixed_bytes_sequence" in field.metadata or "decode_fixed_bytes_sequence" in field.metadata:
+                imports.add("from ._serde_helpers import decode_fixed_bytes_sequence, encode_fixed_bytes_sequence")
             if "nested(" in field.metadata:
                 uses_nested = True
             if "flatten(" in field.metadata:
@@ -585,6 +595,15 @@ def _build_metadata(self, wire_name: str, type_info: TypeInfo, *, required: bool
                 "        )"
             )
         if type_info.is_list and type_info.list_inner_is_bytes:
+            # Handle fixed-length bytes in sequences
+            if type_info.list_inner_byte_length is not None:
+                return (
+                    "wire(\n"
+                    f'            "{alias}",\n'
+                    f"            encode=lambda v: encode_fixed_bytes_sequence(v, {type_info.list_inner_byte_length}),\n"
+                    f"            decode=lambda raw: decode_fixed_bytes_sequence(raw, {type_info.list_inner_byte_length}),\n"
+                    "        )"
+                )
             return (
                 "wire(\n"
                 f'            "{alias}",\n'
@@ -593,6 +612,15 @@ def _build_metadata(self, wire_name: str, type_info: TypeInfo, *, required: bool
                 "        )"
             )
         if type_info.is_bytes:
+            # Handle fixed-length bytes
+            if type_info.byte_length is not None:
+                return (
+                    "wire(\n"
+                    f'            "{alias}",\n'
+                    f"            encode=lambda v: encode_fixed_bytes_base64(v, {type_info.byte_length}),\n"
+                    f"            decode=lambda raw: decode_fixed_bytes_base64(raw, {type_info.byte_length}),\n"
+                    "        )"
+                )
             return (
                 "wire(\n"
                 f'            "{alias}",\n'
@@ -908,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

@@ -26,9 +26,14 @@ class TemplateRenderer:
         "BlockStateProofTracking",
         "ParticipationUpdates",
         "SignedTxnInBlock",
+        "SignedTxnWithAD",
+        "TxnCommitments",
+        "RewardState",
+        "UpgradeState",
+        "UpgradeVote",
         "BlockHeader",
         "Block",
-        "GetBlock",
+        "BlockResponse",
     ]
     LEDGER_STATE_DELTA_EXPORTS: ClassVar[list[str]] = [
         "LedgerTealValue",
@@ -87,7 +92,9 @@ def render(self, client: ctx.ClientDescriptor, config: GeneratorConfig) -> dict[
         files[models_dir / "__init__.py"] = self._render_template("models/__init__.py.j2", context)
         files[models_dir / "_serde_helpers.py"] = self._render_template("models/_serde_helpers.py.j2", context)
         ledger_model_names = set(LEDGER_STATE_DELTA_MODEL_NAMES)
-        models = [model for model in context["client"].models if model.name not in ledger_model_names]
+        block_model_names = set(self.BLOCK_MODEL_EXPORTS) if client.include_block_models else set()
+        excluded_models = ledger_model_names | block_model_names
+        models = [model for model in context["client"].models if model.name not in excluded_models]
         for model in models:
             model_context = {**context, "model": model}
             files[models_dir / f"{model.module_name}.py"] = self._render_template("models/model.py.j2", model_context)
@@ -132,10 +139,12 @@ def _build_context(self, client: ctx.ClientDescriptor, config: GeneratorConfig)
             model_exports.append("SuggestedParams")
         metadata_usage = self._collect_metadata_usage(client)
         ledger_model_names = set(LEDGER_STATE_DELTA_MODEL_NAMES)
+        block_model_names = set(self.BLOCK_MODEL_EXPORTS) if client.include_block_models else set()
+        excluded_models = ledger_model_names | block_model_names
         model_modules = [
             {"module": model.module_name, "name": model.name}
             for model in client.models
-            if model.name not in ledger_model_names
+            if model.name not in excluded_models
         ]
         enum_modules = [{"module": enum.module_name, "name": enum.name} for enum in client.enums]
         alias_modules = [{"module": alias.module_name, "name": alias.name} for alias in client.aliases]

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

@@ -37,6 +37,22 @@ def decode_bytes_base64(raw: object) -> bytes:
     raise TypeError(f"Unsupported value for bytes field: {type(raw)!r}")
 
 
+def encode_fixed_bytes_base64(value: BytesLike, expected_length: int) -> str:
+    """Encode fixed-length bytes to base64, validating the length."""
+    coerced = _coerce_bytes(value)
+    if len(coerced) != expected_length:
+        raise ValueError(f"Expected {expected_length} bytes, got {len(coerced)}")
+    return base64.b64encode(coerced).decode("ascii")
+
+
+def decode_fixed_bytes_base64(raw: object, expected_length: int) -> bytes:
+    """Decode base64 to fixed-length bytes, validating the length."""
+    decoded = decode_bytes_base64(raw)
+    if len(decoded) != expected_length:
+        raise ValueError(f"Expected {expected_length} bytes, got {len(decoded)}")
+    return decoded
+
+
 def decode_bytes_map_key(raw: object) -> bytes:
     if isinstance(raw, bytes | bytearray | memoryview):
         return bytes(raw)
@@ -77,6 +93,36 @@ def decode_bytes_sequence(raw: object) -> list[bytes | None] | None:
     return decoded or None
 
 
+def encode_fixed_bytes_sequence(
+    values: Iterable[BytesLike | None] | None, expected_length: int
+) -> list[str | None] | None:
+    """Encode a sequence of fixed-length bytes to base64, validating each element's length."""
+    if values is None:
+        return None
+    encoded: list[str | None] = []
+    for value in values:
+        if value is None:
+            encoded.append(None)
+            continue
+        if not isinstance(value, bytes | bytearray | memoryview):
+            raise TypeError(f"Unsupported value for bytes field sequence: {type(value)!r}")
+        encoded.append(encode_fixed_bytes_base64(value, expected_length))
+    return encoded or None
+
+
+def decode_fixed_bytes_sequence(raw: object, expected_length: int) -> list[bytes | None] | None:
+    """Decode a sequence of base64 strings to fixed-length bytes, validating each element's length."""
+    if not isinstance(raw, list):
+        return None
+    decoded: list[bytes | None] = []
+    for item in raw:
+        if item is None:
+            decoded.append(None)
+            continue
+        decoded.append(decode_fixed_bytes_base64(item, expected_length))
+    return decoded or None
+
+
 def encode_model_sequence(values: Iterable[object] | None) -> list[dict[str, object]] | None:
     if values is None:
         return None