feat: app manager; asset manager; creator and sender abstractions (#229)

feat: app manager; asset manager; creator and sender abstractions

This commit introduces comprehensive high-level abstractions for Algorand application
and asset management, along with ergonomic transaction creation interfaces that
significantly improve developer experience while maintaining full protocol capability.

## Core Features Added

### Application Manager (`app_manager.rs`)
- Complete application lifecycle management (create, update, delete, call)
- ABI method integration with automatic encoding/decoding
- Box storage operations with binary key support and ABI type decoding
- TEAL compilation with SHA256-based caching for performance
- Application state retrieval with binary key handling for cross-language consistency

### Asset Manager (`asset_manager.rs`)
- Asset creation, configuration, and lifecycle management
- Bulk opt-in/opt-out operations for efficient batch processing
- Asset information retrieval with flattened ergonomic interface
- Account asset information access with proper type handling

### Transaction Abstractions
- **Creator** (`creator.rs`): Fluent transaction building without automatic sending
- **Sender** (`sender.rs`): Direct transaction creation and execution
- **Sender Results** (`sender_results.rs`): Rich result types with transaction metadata
- Unified error handling and validation across all transaction types

## API Client Enhancements

### Generated Client Improvements
- Vendor extension system for field customization (application-index → app_id, asset-index → asset_id)
- Proper binary data handling with base64 deserialization for TealValue.bytes
- Consistent field naming across algod and indexer clients
- Generator-level fixes to avoid manual modification of auto-generated code

### AlgorandClient Integration
- Memory-efficient Arc<AlgodClient> sharing to eliminate unnecessary cloning
- Integrated manager instances for streamlined access patterns
- Comprehensive test utilities with ergonomic Arc-based fixtures

## Developer Experience Improvements

### Type Safety & Ergonomics
- AssetInformation with flattened field access (asset.total vs asset.params.total)
- Optional close_remainder_to in asset opt-out with automatic creator resolution
- Consistent app_id/asset_id naming throughout the API surface
- Rich transaction result types with compilation metadata

### Cross-Language Consistency
- Binary key handling in application state for TypeScript/Python alignment
- Vec<u8> box identifiers for proper non-UTF-8 support
- Standardized ABI return handling across all operations
- Consistent validation patterns between creator and sender abstractions

## Technical Architecture

### Performance Optimizations
- TEAL compilation caching with SHA256 keys for large programs
- Arc-based client sharing to minimize memory overhead
- Bulk operations using TransactionComposer for efficient execution
- Early validation with comprehensive error propagation

### Code Organization
- Clean separation of concerns between managers, creators, and senders
- Leveraged existing algokit_transact validation instead of duplication
- Modular design enabling incremental adoption
- Comprehensive test coverage with deterministic validation

## Breaking Changes
- AssetManager.get_by_id() returns AssetInformation instead of raw algod types
- AssetOptOutParams.creator renamed to close_remainder_to for clarity
- Some method names updated for consistency (_method_call suffix for ABI methods)

## Migration Benefits
This foundation enables the upcoming AlgoKit App Client while providing immediate
value for direct usage. The abstractions eliminate boilerplate while preserving
full protocol access, supporting both simple operations and complex multi-transaction
workflows.

Addresses 45+ PR review comments with architectural improvements, performance
optimizations, and API refinements based on extensive feedback integration.

Author: aorumbayev

api/oas_generator/rust_oas_generator/parser/oas_parser.py

@@ -380,8 +380,17 @@ class Property:
     is_signed_transaction: bool = field(init=False)
 
     def __post_init__(self) -> None:
-        self.rust_name = rust_snake_case(self.name)
+        # Check for field name override from vendor extension
+        field_name_override = self._get_field_name_override()
+        field_name = field_name_override if field_name_override else self.name
+
+        self.rust_name = rust_snake_case(field_name)
         self.rust_field_name = escape_rust_keyword(self.rust_name)
+
+        # Check for bytes base64 override from vendor extension
+        if self._has_bytes_base64_extension():
+            self.is_base64_encoded = True
+
         if self.is_base64_encoded:
             self.rust_type_with_msgpack = "Vec<u8>"
         elif self.items and self.items.is_base64_encoded and self.rust_type.startswith("Vec<"):
@@ -399,6 +408,20 @@ def __post_init__(self) -> None:
                 "x-algokit-signed-txn" in ext_name and ext_value for ext_name, ext_value in self.items.vendor_extensions
             )
 
+    def _get_field_name_override(self) -> str | None:
+        """Get field name override from vendor extension."""
+        for ext_name, ext_value in self.vendor_extensions:
+            if ext_name == "x-algokit-field-rename" and isinstance(ext_value, str):
+                return ext_value
+        return None
+
+    def _has_bytes_base64_extension(self) -> bool:
+        """Check if this property has the bytes base64 vendor extension."""
+        for ext_name, ext_value in self.vendor_extensions:
+            if ext_name == "x-algokit-bytes-base64" and ext_value is True:
+                return True
+        return False
+
 
 @dataclass
 class Schema:

api/scripts/convert-openapi.ts

@@ -183,6 +183,90 @@ function transformVendorExtensions(spec: OpenAPISpec, transforms: VendorExtensio
   return transformCounts;
 }
 
+/**
+ * Fix field naming - Add field rename extensions for better Rust ergonomics
+ */
+function fixFieldNaming(spec: OpenAPISpec): number {
+  let fixedCount = 0;
+
+  // Properties that should be renamed for better developer experience
+  const fieldRenames = [
+    { from: "application-index", to: "app_id" },
+    { from: "asset-index", to: "asset_id" },
+  ];
+
+  const processObject = (obj: any): void => {
+    if (!obj || typeof obj !== "object") return;
+
+    if (Array.isArray(obj)) {
+      obj.forEach((o) => processObject(o));
+      return;
+    }
+
+    // Look for properties object in schemas
+    if (obj.properties && typeof obj.properties === "object") {
+      for (const [propName, propDef] of Object.entries(obj.properties as Record<string, any>)) {
+        if (propDef && typeof propDef === "object") {
+          const rename = fieldRenames.find(r => r.from === propName);
+          if (rename) {
+            propDef["x-algokit-field-rename"] = rename.to;
+            fixedCount++;
+          }
+        }
+      }
+    }
+
+    // Recursively process nested objects
+    for (const value of Object.values(obj)) {
+      if (value && typeof value === "object") {
+        processObject(value);
+      }
+    }
+  };
+
+  processObject(spec);
+  return fixedCount;
+}
+
+/**
+ * Fix TealValue bytes - Add base64 extension for TealValue.bytes fields
+ */
+function fixTealValueBytes(spec: OpenAPISpec): number {
+  let fixedCount = 0;
+
+  const processObject = (obj: any, schemaName?: string): void => {
+    if (!obj || typeof obj !== "object") return;
+
+    if (Array.isArray(obj)) {
+      obj.forEach((o) => processObject(o));
+      return;
+    }
+
+    // Check if this is a TealValue schema with bytes property
+    if (schemaName === "TealValue" && obj.properties && obj.properties.bytes) {
+      obj.properties.bytes["x-algokit-bytes-base64"] = true;
+      fixedCount++;
+    }
+
+    // Recursively process schemas
+    if (obj.schemas && typeof obj.schemas === "object") {
+      for (const [name, schemaDef] of Object.entries(obj.schemas)) {
+        processObject(schemaDef, name);
+      }
+    } else {
+      // Recursively process other nested objects
+      for (const [key, value] of Object.entries(obj)) {
+        if (value && typeof value === "object") {
+          processObject(value, key);
+        }
+      }
+    }
+  };
+
+  processObject(spec);
+  return fixedCount;
+}
+
 /**
  * Fix bigint - Add x-algokit-bigint: true to properties that represent large integers
  */
@@ -370,11 +454,19 @@ class OpenAPIProcessor {
       const pydanticCount = fixPydanticRecursionError(spec);
       console.log(`ℹ️  Fixed ${pydanticCount} pydantic recursion errors`);
 
-      // 3. Fix bigint properties
-      const bigIntCount = fixBigInt(spec);
-      console.log(`ℹ️  Added x-algokit-bigint to ${bigIntCount} properties`);
+       // 3. Fix field naming
+       const fieldNamingCount = fixFieldNaming(spec);
+       console.log(`ℹ️  Added field rename extensions to ${fieldNamingCount} properties`);
+
+       // 4. Fix TealValue bytes fields
+       const tealValueCount = fixTealValueBytes(spec);
+       console.log(`ℹ️  Added bytes base64 extensions to ${tealValueCount} TealValue.bytes properties`);
+
+       // 5. Fix bigint properties
+       const bigIntCount = fixBigInt(spec);
+       console.log(`ℹ️  Added x-algokit-bigint to ${bigIntCount} properties`);
 
-      // 4. Transform vendor extensions if configured
+       // 6. Transform vendor extensions if configured
       if (this.config.vendorExtensionTransforms && this.config.vendorExtensionTransforms.length > 0) {
         const transformCounts = transformVendorExtensions(spec, this.config.vendorExtensionTransforms);
 

api/specs/algod.oas3.json

@@ -5632,7 +5632,8 @@
           },
           "bytes": {
             "type": "string",
-            "description": "\\[tb\\] bytes value."
+            "description": "\\[tb\\] bytes value.",
+            "x-algokit-bytes-base64": true
           },
           "uint": {
             "type": "integer",
@@ -6272,12 +6273,14 @@
             "type": "integer",
             "description": "The asset index if the transaction was found and it created an asset.",
             "x-go-type": "basics.AssetIndex",
+            "x-algokit-field-rename": "asset_id",
             "x-algokit-bigint": true
           },
           "application-index": {
             "type": "integer",
             "description": "The application index if the transaction was found and it created an application.",
             "x-go-type": "basics.AppIndex",
+            "x-algokit-field-rename": "app_id",
             "x-algokit-bigint": true
           },
           "close-rewards": {
@@ -6831,6 +6834,7 @@
             "type": "integer",
             "description": "The application from which the logs were generated",
             "x-go-type": "basics.AppIndex",
+            "x-algokit-field-rename": "app_id",
             "x-algokit-bigint": true
           },
           "txId": {

api/specs/indexer.oas3.json

@@ -3400,7 +3400,8 @@
           },
           "bytes": {
             "type": "string",
-            "description": "bytes value."
+            "description": "bytes value.",
+            "x-algokit-bytes-base64": true
           },
           "uint": {
             "type": "integer",

crates/algod_client/src/models/app_call_logs.rs

@@ -22,18 +22,18 @@ pub struct AppCallLogs {
     pub logs: Vec<Vec<u8>>,
     /// The application from which the logs were generated
     #[serde(rename = "application-index")]
-    pub application_index: u64,
+    pub app_id: u64,
     /// The transaction ID of the outer app call that lead to these logs
     #[serde(rename = "txId")]
     pub tx_id: String,
 }
 
 impl AppCallLogs {
     /// Constructor for AppCallLogs
-    pub fn new(logs: Vec<Vec<u8>>, application_index: u64, tx_id: String) -> AppCallLogs {
+    pub fn new(logs: Vec<Vec<u8>>, app_id: u64, tx_id: String) -> AppCallLogs {
         AppCallLogs {
             logs,
-            application_index,
+            app_id,
             tx_id,
         }
     }

crates/algod_client/src/models/pending_transaction_response.rs

@@ -22,10 +22,10 @@ use crate::models::StateDelta;
 pub struct PendingTransactionResponse {
     /// The asset index if the transaction was found and it created an asset.
     #[serde(rename = "asset-index", skip_serializing_if = "Option::is_none")]
-    pub asset_index: Option<u64>,
+    pub asset_id: Option<u64>,
     /// The application index if the transaction was found and it created an application.
     #[serde(rename = "application-index", skip_serializing_if = "Option::is_none")]
-    pub application_index: Option<u64>,
+    pub app_id: Option<u64>,
     /// Rewards in microalgos applied to the close remainder to account.
     #[serde(rename = "close-rewards", skip_serializing_if = "Option::is_none")]
     pub close_rewards: Option<u64>,
@@ -70,8 +70,8 @@ pub struct PendingTransactionResponse {
 impl Default for PendingTransactionResponse {
     fn default() -> Self {
         Self {
-            asset_index: None,
-            application_index: None,
+            asset_id: None,
+            app_id: None,
             close_rewards: None,
             closing_amount: None,
             asset_closing_amount: None,
@@ -121,8 +121,8 @@ impl PendingTransactionResponse {
         PendingTransactionResponse {
             pool_error,
             txn,
-            asset_index: None,
-            application_index: None,
+            asset_id: None,
+            app_id: None,
             close_rewards: None,
             closing_amount: None,
             asset_closing_amount: None,

crates/algod_client/src/models/teal_value.rs

@@ -11,16 +11,19 @@
 use crate::models;
 use algokit_transact::{AlgorandMsgpack, SignedTransaction as AlgokitSignedTransaction};
 use serde::{Deserialize, Serialize};
+use serde_with::{Bytes, serde_as};
 
 /// Represents a TEAL value.
+#[serde_as]
 #[derive(Clone, Default, Debug, PartialEq, Serialize, Deserialize)]
 pub struct TealValue {
     /// \[tt\] value type. Value `1` refers to **bytes**, value `2` refers to **uint**
     #[serde(rename = "type")]
     pub r#type: u64,
     /// \[tb\] bytes value.
+    #[serde_as(as = "serde_with::base64::Base64")]
     #[serde(rename = "bytes")]
-    pub bytes: String,
+    pub bytes: Vec<u8>,
     /// \[ui\] uint value.
     #[serde(rename = "uint")]
     pub uint: u64,
@@ -32,7 +35,7 @@ impl AlgorandMsgpack for TealValue {
 
 impl TealValue {
     /// Constructor for TealValue
-    pub fn new(r#type: u64, bytes: String, uint: u64) -> TealValue {
+    pub fn new(r#type: u64, bytes: Vec<u8>, uint: u64) -> TealValue {
         TealValue {
             r#type,
             bytes,

crates/algokit_abi/src/lib.rs

@@ -14,6 +14,6 @@ pub use arc56_contract::*;
 pub use error::ABIError;
 
 pub use method::{
-    ABIMethod, ABIMethodArg, ABIMethodArgType, ABIReferenceType, ABIReferenceValue,
+    ABIMethod, ABIMethodArg, ABIMethodArgType, ABIReferenceType, ABIReferenceValue, ABIReturn,
     ABITransactionType,
 };

crates/algokit_abi/src/method.rs

@@ -1,4 +1,5 @@
 use crate::abi_type::ABIType;
+use crate::abi_value::ABIValue;
 use crate::error::ABIError;
 use sha2::{Digest, Sha512_256};
 use std::fmt::Display;
@@ -357,6 +358,17 @@ impl ABIMethodArg {
     }
 }
 
+/// Represents an ABI method return value with parsed data.
+#[derive(Debug, Clone)]
+pub struct ABIReturn {
+    /// The method that was called.
+    pub method: ABIMethod,
+    /// The raw return value as bytes.
+    pub raw_return_value: Vec<u8>,
+    /// The parsed ABI return value.
+    pub return_value: ABIValue,
+}
+
 /// Find the matching closing parenthesis for an opening parenthesis.
 fn find_matching_closing_paren(s: &str, open_pos: usize) -> Result<usize, ABIError> {
     let chars: Vec<char> = s.chars().collect();

crates/algokit_test_artifacts/src/lib.rs

@@ -4,7 +4,7 @@
 //!
 //! This crate provides static access to various Algorand contract artifacts
 //! used for testing purposes. Artifacts are organized by contract name in
-//! individual folders, following the Python algokit-utils convention.
+//! individual folders.
 //!
 //! Each contract has its own folder named after the contract, containing
 //! standardized file names like `application.arc56.json` or `application.json`.