refactor: decouples reference type attribute names (#237)

* fix: align reference type attribute names with wire format using metadata

- Add wire() metadata to BoxReference, HoldingReference, and LocalsReference dataclasses
  to specify API wire format field names (app, asset, account, name)
- Use Pythonic field names in code (app_id, asset_id, address) for better API consistency
- Add _decode_address_field helper to handle address decoding from wire format
- Update composer_resources.py and transaction_composer.py to use new attribute names

This fixes attribute mismatches where the API wire format uses short names (app, asset,
account) but our dataclasses should use descriptive Python naming conventions (app_id,
asset_id, address).

* refactor: align against latest specs with plural num_* keys aligning with transact naming

* chore: temporarily change branch to point to pr on oas generator with new specs

* chore: set schemas branch back to main

Author: aorumbayev

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

@@ -29,6 +29,9 @@ class TypeInfo:
     is_bytes: bool = False
     list_inner_is_bytes: bool = False
     is_signed_transaction: bool = False
+    is_box_reference: bool = False
+    is_locals_reference: bool = False
+    is_holding_reference: bool = False
     needs_datetime: bool = False
     imports: set[str] = field(default_factory=set)
 
@@ -116,6 +119,12 @@ def _classify(self, schema: ctx.RawSchema) -> str:
             return "enum"
         if schema.get("x-algokit-signed-txn"):
             return "signed"
+        if schema.get("x-algokit-box-reference"):
+            return "box_reference"
+        if schema.get("x-algokit-locals-reference"):
+            return "locals_reference"
+        if schema.get("x-algokit-holding-reference"):
+            return "holding_reference"
         if schema.get("type") == "object" or schema.get("properties"):
             return "model"
         return "alias"
@@ -142,6 +151,15 @@ def resolve(self, schema: ctx.RawSchema, *, hint: str = "Inline") -> TypeInfo:
         if schema.get("x-algokit-signed-txn"):
             info = TypeInfo(annotation="SignedTransaction", model="SignedTransaction", is_signed_transaction=True)
             return self._maybe_optional(info, nullable=nullable)
+        if schema.get("x-algokit-box-reference"):
+            info = TypeInfo(annotation="BoxReference", model="BoxReference", is_box_reference=True)
+            return self._maybe_optional(info, nullable=nullable)
+        if schema.get("x-algokit-locals-reference"):
+            info = TypeInfo(annotation="LocalsReference", model="LocalsReference", is_locals_reference=True)
+            return self._maybe_optional(info, nullable=nullable)
+        if schema.get("x-algokit-holding-reference"):
+            info = TypeInfo(annotation="HoldingReference", model="HoldingReference", is_holding_reference=True)
+            return self._maybe_optional(info, nullable=nullable)
         if schema_type == "array":
             info = self._resolve_array(schema, hint=hint)
             return self._maybe_optional(info, nullable=nullable)
@@ -183,6 +201,12 @@ def _type_from_entry(self, entry: SchemaEntry, *, hint: str) -> TypeInfo:
             return TypeInfo(annotation=entry.python_name, enum=entry.python_name)
         if entry.kind == "signed":
             return TypeInfo(annotation="SignedTransaction", model="SignedTransaction", is_signed_transaction=True)
+        if entry.kind == "box_reference":
+            return TypeInfo(annotation="BoxReference", model="BoxReference", is_box_reference=True)
+        if entry.kind == "locals_reference":
+            return TypeInfo(annotation="LocalsReference", model="LocalsReference", is_locals_reference=True)
+        if entry.kind == "holding_reference":
+            return TypeInfo(annotation="HoldingReference", model="HoldingReference", is_holding_reference=True)
         return self.resolve(entry.schema, hint=hint)
 
     def _resolve_array(self, schema: ctx.RawSchema, *, hint: str) -> TypeInfo:
@@ -196,6 +220,9 @@ def _resolve_array(self, schema: ctx.RawSchema, *, hint: str) -> TypeInfo:
             list_inner_enum=inner.enum,
             list_inner_is_bytes=inner.is_bytes,
             is_signed_transaction=inner.is_signed_transaction,
+            is_box_reference=inner.is_box_reference,
+            is_locals_reference=inner.is_locals_reference,
+            is_holding_reference=inner.is_holding_reference,
             needs_datetime=inner.needs_datetime,
             imports=set(inner.imports),
         )
@@ -212,6 +239,9 @@ def __init__(self, registry: SchemaRegistry, resolver: TypeResolver, sanitizer:
         self.resolver = resolver
         self.sanitizer = sanitizer
         self.uses_signed_transaction = False
+        self.uses_box_reference = False
+        self.uses_locals_reference = False
+        self.uses_holding_reference = False
 
     def _compute_default_value(self, type_info: TypeInfo, prop_schema: ctx.RawSchema) -> str | None:
         """Compute default value for a required field based on its type.
@@ -293,6 +323,9 @@ def build(self) -> tuple[list[ctx.ModelDescriptor], list[ctx.EnumDescriptor], li
                 models.append(self._build_model(entry))
             elif entry.kind == "enum":
                 enums.append(self._build_enum(entry))
+            elif entry.kind in ("signed", "box_reference", "locals_reference", "holding_reference"):
+                # These are imported from algokit_transact, not generated
+                pass
             elif entry.kind == "alias":
                 alias_type = self.resolver.resolve(entry.schema).annotation
                 alias_imports = self._collect_alias_imports(alias_type, entry)
@@ -328,6 +361,15 @@ def _build_model(self, entry: SchemaEntry) -> ctx.ModelDescriptor:  # noqa: C901
             if type_info.is_signed_transaction:
                 self.uses_signed_transaction = True
                 imports.add("from algokit_transact.models.signed_transaction import SignedTransaction")
+            if type_info.is_box_reference:
+                self.uses_box_reference = True
+                imports.add("from algokit_transact.models.app_call import BoxReference")
+            if type_info.is_locals_reference:
+                self.uses_locals_reference = True
+                imports.add("from algokit_transact.models.app_call import LocalsReference")
+            if type_info.is_holding_reference:
+                self.uses_holding_reference = True
+                imports.add("from algokit_transact.models.app_call import HoldingReference")
             annotation = type_info.annotation
             if prop_name not in required and "| None" not in annotation:
                 annotation = f"{annotation} | None"
@@ -384,13 +426,22 @@ def _build_model(self, entry: SchemaEntry) -> ctx.ModelDescriptor:  # noqa: C901
                     if dep_module != entry.module_name:
                         imports.add(f"from .{dep_module} import {dep_entry.python_name}")
             if type_info.list_inner_model:
-                dep_entry = self.registry.entries_by_python_name.get(type_info.list_inner_model)
-                if dep_entry:
-                    dep_module = _get_import_module(dep_entry.python_name, dep_entry.module_name)
-                    if dep_module != entry.module_name:
-                        imports.add(f"from .{dep_module} import {dep_entry.python_name}")
+                # Handle special external types first
                 if type_info.list_inner_model == "SignedTransaction":
                     imports.add("from algokit_transact.models.signed_transaction import SignedTransaction")
+                elif type_info.list_inner_model == "BoxReference" and type_info.is_box_reference:
+                    imports.add("from algokit_transact.models.app_call import BoxReference")
+                elif type_info.list_inner_model == "LocalsReference" and type_info.is_locals_reference:
+                    imports.add("from algokit_transact.models.app_call import LocalsReference")
+                elif type_info.list_inner_model == "HoldingReference" and type_info.is_holding_reference:
+                    imports.add("from algokit_transact.models.app_call import HoldingReference")
+                else:
+                    # Only add local import if not a special external type
+                    dep_entry = self.registry.entries_by_python_name.get(type_info.list_inner_model)
+                    if dep_entry:
+                        dep_module = _get_import_module(dep_entry.python_name, dep_entry.module_name)
+                        if dep_module != entry.module_name:
+                            imports.add(f"from .{dep_module} import {dep_entry.python_name}")
             if type_info.enum:
                 dep_entry = self.registry.entries_by_python_name.get(type_info.enum)
                 if dep_entry:
@@ -483,7 +534,7 @@ def _forward_reference_tokens(self, entry: SchemaEntry, type_info: TypeInfo) ->
     def _requires_direct_forward_reference(self, entry: SchemaEntry, type_info: TypeInfo) -> bool:
         if not type_info.model:
             return False
-        if type_info.model == "SignedTransaction":
+        if type_info.model in ("SignedTransaction", "BoxReference", "LocalsReference", "HoldingReference"):
             return False
         if type_info.model == entry.python_name:
             return True
@@ -551,6 +602,12 @@ def _build_metadata(self, wire_name: str, type_info: TypeInfo, *, required: bool
             )
         if type_info.is_signed_transaction:
             return f'nested("{alias}", lambda: SignedTransaction)'
+        if type_info.is_box_reference:
+            return f'nested("{alias}", lambda: BoxReference)'
+        if type_info.is_locals_reference:
+            return f'nested("{alias}", lambda: LocalsReference)'
+        if type_info.is_holding_reference:
+            return f'nested("{alias}", lambda: HoldingReference)'
         return f'wire("{alias}")'
 
     def _collect_alias_imports(self, annotation: str, entry: SchemaEntry) -> list[str]:
@@ -580,6 +637,15 @@ def _collect_alias_imports(self, annotation: str, entry: SchemaEntry) -> list[st
             if token == "SignedTransaction":
                 imports.add("from algokit_transact.models.signed_transaction import SignedTransaction")
                 continue
+            if token == "BoxReference":
+                imports.add("from algokit_transact.models.app_call import BoxReference")
+                continue
+            if token == "LocalsReference":
+                imports.add("from algokit_transact.models.app_call import LocalsReference")
+                continue
+            if token == "HoldingReference":
+                imports.add("from algokit_transact.models.app_call import HoldingReference")
+                continue
             dep_entry = self.registry.entries_by_python_name.get(token)
             if dep_entry:
                 imports.add(f"from .{dep_entry.module_name} import {dep_entry.python_name}")
@@ -941,6 +1007,9 @@ def build_client_descriptor(
         default_base_url=base_url,
         token_header=token_header,
         uses_signed_transaction=uses_signed_txn,
+        uses_box_reference=model_builder.uses_box_reference,
+        uses_locals_reference=model_builder.uses_locals_reference,
+        uses_holding_reference=model_builder.uses_holding_reference,
         uses_msgpack=operation_builder.uses_msgpack,
         include_block_models=operation_builder.uses_block_models,
         include_ledger_state_delta=operation_builder.uses_ledger_state_delta,

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

@@ -153,6 +153,9 @@ class ClientDescriptor:
     default_base_url: str
     token_header: str
     uses_signed_transaction: bool = False
+    uses_box_reference: bool = False
+    uses_locals_reference: bool = False
+    uses_holding_reference: bool = False
     uses_msgpack: bool = False
     include_block_models: bool = False
     is_algod_client: bool = False

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

@@ -1,6 +1,9 @@
 
 
 {% if client.uses_signed_transaction %}from algokit_transact.models.signed_transaction import SignedTransaction
+{% endif %}{% if client.uses_box_reference %}from algokit_transact.models.app_call import BoxReference
+{% endif %}{% if client.uses_locals_reference %}from algokit_transact.models.app_call import LocalsReference
+{% endif %}{% if client.uses_holding_reference %}from algokit_transact.models.app_call import HoldingReference
 {% endif %}{% for item in model_modules %}from .{{ item.module }} import {{ item.name }}
 {% endfor %}{% for item in enum_modules %}from .{{ item.module }} import {{ item.name }}
 {% endfor %}{% for item in alias_modules %}from .{{ item.module }} import {{ item.name }}
@@ -14,6 +17,9 @@
 {% endif %}
 
 __all__ = [
-    {% for name in model_exports %}"{{ name }}",
+    {% if client.uses_box_reference %}"BoxReference",
+    {% endif %}{% if client.uses_locals_reference %}"LocalsReference",
+    {% endif %}{% if client.uses_holding_reference %}"HoldingReference",
+    {% endif %}{% for name in model_exports %}"{{ name }}",
     {% endfor %}
 ]

src/algokit_algod_client/models/__init__.py

@@ -1,6 +1,7 @@
 # AUTO-GENERATED: oas_generator
 
 
+from algokit_transact.models.app_call import BoxReference, HoldingReference, LocalsReference
 from algokit_transact.models.signed_transaction import SignedTransaction
 
 from ._account import Account
@@ -13,14 +14,12 @@
 from ._application import Application
 from ._application_initial_states import ApplicationInitialStates
 from ._application_kvstorage import ApplicationKvstorage
-from ._application_local_reference import ApplicationLocalReference
 from ._application_local_state import ApplicationLocalState
 from ._application_params import ApplicationParams
 from ._application_state_operation import ApplicationStateOperation
 from ._application_state_schema import ApplicationStateSchema
 from ._asset import Asset
 from ._asset_holding import AssetHolding
-from ._asset_holding_reference import AssetHoldingReference
 from ._asset_params import AssetParams
 from ._avm_key_value import AvmKeyValue
 from ._avm_value import AvmValue
@@ -43,7 +42,6 @@
 from ._block_txids_response import BlockTxidsResponse
 from ._box import Box
 from ._box_descriptor import BoxDescriptor
-from ._box_reference import BoxReference
 from ._boxes_response import BoxesResponse
 from ._build_version_contains_the_current_algod_build_version_information import (
     BuildVersionContainsTheCurrentAlgodBuildVersionInformation,
@@ -125,15 +123,13 @@
     "Application",
     "ApplicationInitialStates",
     "ApplicationKvstorage",
-    "ApplicationLocalReference",
     "ApplicationLocalState",
     "ApplicationParams",
     "ApplicationStateOperation",
     "ApplicationStateSchema",
     "ApplyData",
     "Asset",
     "AssetHolding",
-    "AssetHoldingReference",
     "AssetParams",
     "AvmKeyValue",
     "AvmValue",
@@ -163,6 +159,7 @@
     "GetBlockTimeStampOffsetResponse",
     "GetSyncRoundResponse",
     "GetTransactionGroupLedgerStateDeltasForRound",
+    "HoldingReference",
     "LedgerAccountBaseData",
     "LedgerAccountData",
     "LedgerAccountDeltas",
@@ -188,6 +185,7 @@
     "LedgerTealValue",
     "LedgerVotingData",
     "LightBlockHeaderProof",
+    "LocalsReference",
     "NodeStatusResponse",
     "ParticipationUpdates",
     "PendingTransactionResponse",

src/algokit_algod_client/models/_application_local_reference.py

@@ -12,11 +12,11 @@ class ApplicationStateSchema:
     Specifies maximums on the number of each type that may be stored.
     """
 
-    num_byte_slice: int = field(
+    num_byte_slices: int = field(
         default=0,
         metadata=wire("num-byte-slice"),
     )
-    num_uint: int = field(
+    num_uints: int = field(
         default=0,
         metadata=wire("num-uint"),
     )

src/algokit_algod_client/models/_application_state_schema.py

@@ -4,10 +4,8 @@
 from dataclasses import dataclass, field
 
 from algokit_common.serde import wire
+from algokit_transact.models.app_call import BoxReference, HoldingReference, LocalsReference
 
-from ._application_local_reference import ApplicationLocalReference
-from ._asset_holding_reference import AssetHoldingReference
-from ._box_reference import BoxReference
 from ._serde_helpers import decode_model_sequence, encode_model_sequence
 
 
@@ -28,24 +26,24 @@ class SimulateUnnamedResourcesAccessed:
         default=None,
         metadata=wire("accounts"),
     )
-    app_locals: list[ApplicationLocalReference] | None = field(
+    app_locals: list[LocalsReference] | None = field(
         default=None,
         metadata=wire(
             "app-locals",
             encode=encode_model_sequence,
-            decode=lambda raw: decode_model_sequence(lambda: ApplicationLocalReference, raw),
+            decode=lambda raw: decode_model_sequence(lambda: LocalsReference, raw),
         ),
     )
     apps: list[int] | None = field(
         default=None,
         metadata=wire("apps"),
     )
-    asset_holdings: list[AssetHoldingReference] | None = field(
+    asset_holdings: list[HoldingReference] | None = field(
         default=None,
         metadata=wire(
             "asset-holdings",
             encode=encode_model_sequence,
-            decode=lambda raw: decode_model_sequence(lambda: AssetHoldingReference, raw),
+            decode=lambda raw: decode_model_sequence(lambda: HoldingReference, raw),
         ),
     )
     assets: list[int] | None = field(