@goplausible/algorand-mcp 3.0.7

package/dist/resources/knowledge/taxonomy/developer:python:code:example:box_storage.md

@@ -0,0 +1,211 @@
+# Box Storage in Algorand Smart Contracts
+
+Box storage is a feature in Algorand that allows smart contracts to store and manage data in separate "boxes" outside of the application's global and local state. This guide demonstrates how to use box storage in Algorand Python smart contracts.
+
+## Box Storage Types
+
+```python
+from algopy import (
+    ARC4Contract,
+    Box,
+    BoxMap,
+    BoxRef,
+    Bytes,
+    String,
+    UInt64,
+    arc4,
+)
+
+# Example of a struct that can be stored in a box
+class UserStruct(arc4.Struct):
+    name: arc4.String
+    id: arc4.UInt64
+    asset: arc4.UInt64
+```
+
+### Initializing Box Storage
+
+```python
+class BoxStorage(ARC4Contract):
+    def __init__(self) -> None:
+        # Basic box types
+        self.box_int = Box(UInt64)
+        self.box_dynamic_bytes = Box[arc4.DynamicBytes](arc4.DynamicBytes, key="b")
+        self.box_string = Box(arc4.String, key=b"BOX_C")
+        self.box_bytes = Box(Bytes)
+        
+        # Box map with uint as key and string as value
+        self.box_map = BoxMap(UInt64, String, key_prefix="")
+        
+        # Box reference for direct manipulation
+        self.box_ref = BoxRef()
+        
+        # Box map for storing structs
+        self.box_map_struct = BoxMap(arc4.UInt64, UserStruct, key_prefix="users")
+```
+
+## Basic Box Operations
+
+### Getting Values
+
+```python
+@arc4.abimethod
+def get_box_example(self) -> tuple[UInt64, Bytes, arc4.String]:
+    return (
+        self.box_int.value,                      # Get integer value
+        self.box_dynamic_bytes.value.native,     # Get bytes value
+        self.box_string.value,                   # Get string value
+    )
+
+@arc4.abimethod
+def get_box_map_example(self) -> bool:
+    key_1 = UInt64(1)
+    # Get value with default if not found
+    value = self.box_map.get(key_1, default=String("default"))
+    return True
+```
+
+### Setting Values
+
+```python
+@arc4.abimethod
+def set_box_example(
+    self,
+    value_int: UInt64,
+    value_dbytes: arc4.DynamicBytes,
+    value_string: arc4.String,
+) -> None:
+    # Set values in different box types
+    self.box_int.value = value_int
+    self.box_dynamic_bytes.value = value_dbytes.copy()
+    self.box_string.value = value_string
+    self.box_bytes.value = value_dbytes.native
+
+    # Increment value
+    self.box_int.value += 3
+
+@arc4.abimethod
+def set_box_map_struct(self, key: arc4.UInt64, value: UserStruct) -> bool:
+    # Store struct in box map
+    self.box_map_struct[key] = value.copy()
+    return True
+```
+
+### Deleting Values
+
+```python
+@arc4.abimethod
+def delete_box(self) -> None:
+    # Delete values from boxes
+    del self.box_int.value
+    del self.box_dynamic_bytes.value
+    del self.box_string.value
+
+    # Verify deletion by checking default values
+    assert self.box_int.get(default=UInt64(42)) == 42
+    assert self.box_dynamic_bytes.get(default=arc4.DynamicBytes(b"42")).native == b"42"
+    assert self.box_string.get(default=arc4.String("42")) == "42"
+
+@arc4.abimethod
+def delete_box_map(self, key: UInt64) -> None:
+    # Delete value from box map
+    del self.box_map[key]
+```
+
+## Advanced Box Operations
+
+### Maybe Operations (Safe Access)
+
+```python
+@arc4.abimethod
+def maybe_box(self) -> tuple[UInt64, bool]:
+    # Get value and existence flag
+    box_int_value, box_int_exists = self.box_int.maybe()
+    return box_int_value, box_int_exists
+
+@arc4.abimethod
+def maybe_box_map(self) -> tuple[String, bool]:
+    key_1 = UInt64(1)
+    # Get value and existence flag from map
+    value, exists = self.box_map.maybe(key_1)
+    if not exists:
+        value = String("")
+    return value, exists
+```
+
+### Box References
+
+```python
+@arc4.abimethod
+def manipulate_box_ref(self) -> None:
+    box_ref = BoxRef(key=String("blob"))
+    assert box_ref.create(size=32)
+
+    # Manipulate data
+    sender_bytes = Txn.sender.bytes
+    app_address = Global.current_application_address.bytes
+    value_3 = Bytes(b"hello")
+    
+    # Replace and splice operations
+    box_ref.replace(0, sender_bytes)
+    box_ref.splice(0, 0, app_address)
+    box_ref.replace(64, value_3)
+    
+    # Extract data
+    prefix = box_ref.extract(0, 32 * 2 + value_3.length)
+    
+    # Delete and recreate
+    box_ref.delete()
+    box_ref.put(sender_bytes + app_address)
+```
+
+### Length Operations
+
+```python
+@arc4.abimethod
+def box_map_length(self) -> UInt64:
+    key_0 = UInt64(0)
+    if key_0 not in self.box_map:
+        return UInt64(0)
+    return self.box_map.length(key_0)
+
+@arc4.abimethod
+def length_box_ref(self) -> UInt64:
+    box_ref = BoxRef(key=String("blob"))
+    assert box_ref.create(size=32)
+    return box_ref.length
+```
+
+## Best Practices
+
+1. **Memory Management**:
+   - Use appropriate box sizes to minimize storage costs
+   - Delete unused boxes to free up space
+   - Consider using box references for large data manipulations
+
+2. **Data Safety**:
+   - Use `maybe()` operations when accessing potentially non-existent values
+   - Provide default values when getting box contents
+   - Verify box existence before operations
+
+3. **Struct Storage**:
+   - Use `copy()` when storing struct values to ensure data integrity
+   - Verify struct storage with assertions
+   - Use appropriate key prefixes for organization
+
+4. **Box References**:
+   - Create boxes with appropriate sizes
+   - Use extract and splice operations carefully
+   - Clean up unused box references
+
+5. **Performance**:
+   - Minimize box operations to reduce costs
+   - Use appropriate data types for storage
+   - Consider using box maps for related data
+
+6. **Error Handling**:
+   - Include assertions for critical operations
+   - Handle non-existent boxes gracefully
+   - Verify operation success
+
+This guide demonstrates the various capabilities of box storage in Algorand smart contracts using Python. Box storage provides a flexible way to manage contract data while maintaining efficiency and organization.

package/dist/resources/knowledge/taxonomy/developer:python:code:example:control_flow.md

@@ -0,0 +1,162 @@
+# Control Flow in Algorand Smart Contracts
+
+This guide demonstrates the various control flow structures available in Algorand Python smart contracts, including conditional statements, loops, and pattern matching.
+
+## Conditional Statements (If-Else)
+
+```python
+from algopy import ARC4Contract, String, UInt64, arc4
+
+class IfElseExample(ARC4Contract):
+    @arc4.abimethod
+    def is_rich(self, account_balance: UInt64) -> String:
+        if account_balance > 1000:
+            return String("This account is rich!")
+        elif account_balance > 100:
+            return String("This account is doing well.")
+        else:
+            return String("This account is poor :(")
+
+    @arc4.abimethod
+    def is_even(self, number: UInt64) -> String:
+        # Ternary operator example
+        return String("Even") if number % 2 == 0 else String("Odd")
+```
+
+### Key Points about Conditionals
+- Standard if-elif-else structure is supported
+- Conditions must evaluate to boolean values
+- Ternary operator (`value_if_true if condition else value_if_false`) is supported
+- Type safety is enforced for return values
+
+## For Loops
+
+```python
+import typing as t
+from algopy import ARC4Contract, UInt64, arc4, uenumerate, urange
+
+# Define a static array type
+FourArray: t.TypeAlias = arc4.StaticArray[arc4.UInt8, t.Literal[4]]
+
+class ForLoopsExample(ARC4Contract):
+    @arc4.abimethod
+    def for_loop(self) -> FourArray:
+        array = FourArray(arc4.UInt8(0), arc4.UInt8(0), arc4.UInt8(0), arc4.UInt8(0))
+
+        # Enumerate with reversed range
+        for index, item in uenumerate(reversed(urange(4))):  # [3, 2, 1, 0]
+            array[index] = arc4.UInt8(item)
+
+        # Simple range iteration
+        x = UInt64(0)
+        for item in urange(1, 5):  # [1, 2, 3, 4]
+            x += item
+
+        assert x == 10
+        return array
+```
+
+### Key Points about For Loops
+- Uses `urange` for unsigned integer ranges
+- `uenumerate` provides index and value pairs
+- Supports iteration over static arrays
+- Can use `reversed` with `urange`
+- Loop variables must be properly typed
+
+## Match Statements (Pattern Matching)
+
+```python
+class MatchStatements(ARC4Contract):
+    @arc4.abimethod
+    def get_day(self, date: UInt64) -> String:
+        match date:
+            case UInt64(0):
+                return String("Monday")
+            case UInt64(1):
+                return String("Tuesday")
+            case UInt64(2):
+                return String("Wednesday")
+            case UInt64(3):
+                return String("Thursday")
+            case UInt64(4):
+                return String("Friday")
+            case UInt64(5):
+                return String("Saturday")
+            case UInt64(6):
+                return String("Sunday")
+            case _:
+                return String("Invalid day")
+```
+
+### Key Points about Match Statements
+- Similar to switch statements in other languages
+- Cases must be exhaustive
+- Wildcard pattern (`_`) catches all unmatched cases
+- Values in cases must match the type being matched
+- Each case must return consistent types
+
+## While Loops
+
+```python
+class WhileLoopExample(ARC4Contract):
+    @arc4.abimethod
+    def loop(self) -> UInt64:
+        num = UInt64(10)
+        loop_count = UInt64(0)
+
+        while num > 0:
+            if num > 5:
+                num -= 1
+                loop_count += 1
+                continue
+
+            num -= 2
+            loop_count += 1
+
+            if num == 1:
+                break
+
+        return loop_count
+```
+
+### Key Points about While Loops
+- Condition must evaluate to a boolean
+- Supports `break` to exit the loop
+- Supports `continue` to skip to next iteration
+- Variables modified in loop must be properly typed
+- Be careful with infinite loops (they will fail)
+
+## Best Practices
+
+1. **Type Safety**:
+   - Always use proper types for variables and return values
+   - Be explicit with type conversions
+   - Use type aliases for complex types
+
+2. **Loop Control**:
+   - Use appropriate loop structure for the task
+   - Avoid infinite loops
+   - Consider using `break` and `continue` for control flow
+   - Initialize counters and accumulators properly
+
+3. **Pattern Matching**:
+   - Make match statements exhaustive
+   - Use wildcard pattern (`_`) as last case
+   - Keep cases simple and readable
+
+4. **Conditionals**:
+   - Use clear, simple conditions
+   - Consider using ternary operator for simple if-else
+   - Ensure all branches return consistent types
+
+5. **Performance**:
+   - Keep loops efficient
+   - Avoid unnecessary iterations
+   - Use appropriate data structures
+
+6. **Code Organization**:
+   - Group related control structures
+   - Use meaningful variable names
+   - Add comments for complex logic
+
+This guide demonstrates the various control flow structures available in Algorand Python smart contracts. Understanding and properly using these structures is essential for writing efficient and maintainable smart contracts.

package/dist/resources/knowledge/taxonomy/developer:python:code:example:global_storage.md

@@ -0,0 +1,192 @@
+# Global Storage in Algorand Smart Contracts
+
+This guide demonstrates how to work with global state in Algorand smart contracts using Python. Global state allows contracts to store and manage data that is accessible across all interactions with the contract.
+
+## Initializing Global State
+
+```python
+from algopy import (
+    Account,
+    Application,
+    ARC4Contract,
+    Asset,
+    Bytes,
+    GlobalState,
+    UInt64,
+    arc4,
+)
+
+class GlobalStorage(ARC4Contract):
+    def __init__(self) -> None:
+        # Integer storage
+        self.global_int_full = GlobalState(UInt64(50))        # With default value
+        self.global_int_simplified = UInt64(10)               # Simplified syntax
+        self.global_int_no_default = GlobalState(UInt64)      # No default value
+
+        # Bytes storage
+        self.global_bytes_full = GlobalState(Bytes(b"Hello")) # With default value
+        self.global_bytes_simplified = Bytes(b"Hello")        # Simplified syntax
+        self.global_bytes_no_default = GlobalState(Bytes)     # No default value
+
+        # Boolean storage
+        self.global_bool_simplified = True                    # Simplified boolean
+        self.global_bool_no_default = GlobalState(bool)       # No default value
+
+        # Special types
+        self.global_asset = GlobalState(Asset)               # Asset reference
+        self.global_application = GlobalState(Application)    # Application reference
+        self.global_account = GlobalState(Account)           # Account reference
+```
+
+### Key Points about Initialization
+- Can use `GlobalState` with or without default values
+- Simplified syntax available for basic types
+- Supports various data types including integers, bytes, booleans
+- Special types for assets, applications, and accounts
+
+## Reading Global State
+
+### Basic Reading
+
+```python
+@arc4.abimethod
+def get_global_state(self) -> UInt64:
+    # Get value with default if not set
+    return self.global_int_full.get(default=UInt64(0))
+
+@arc4.abimethod
+def maybe_global_state(self) -> tuple[UInt64, bool]:
+    # Get value and existence flag
+    int_value, int_exists = self.global_int_full.maybe()
+    if not int_exists:
+        int_value = UInt64(0)
+    return int_value, int_exists
+```
+
+### Reading Different Types
+
+```python
+@arc4.abimethod
+def get_global_state_example(self) -> bool:
+    # Reading integers
+    assert self.global_int_full.get(default=UInt64(0)) == 50
+    assert self.global_int_simplified == UInt64(10)
+    
+    # Reading bytes
+    assert self.global_bytes_full.get(Bytes(b"default")) == b"Hello"
+    
+    # Reading special types
+    asset_value, exists = self.global_asset.maybe()
+    assert asset_value == Asset(UInt64(10))
+    
+    app_value, exists = self.global_application.maybe()
+    assert app_value == Application(UInt64(10))
+    
+    return True
+```
+
+## Writing Global State
+
+### Basic Writing
+
+```python
+@arc4.abimethod
+def set_global_state(self, value: Bytes) -> None:
+    self.global_bytes_full.value = value
+
+@arc4.abimethod
+def set_global_state_example(
+    self,
+    value_bytes: Bytes,
+    value_asset: Asset,
+    *,
+    value_bool: bool,
+) -> None:
+    # Setting different types
+    self.global_bytes_no_default.value = value_bytes
+    self.global_bool_no_default.value = value_bool
+    self.global_asset.value = value_asset
+```
+
+## Deleting Global State
+
+```python
+@arc4.abimethod
+def del_global_state(self) -> bool:
+    # Delete a single value
+    del self.global_int_full.value
+    return True
+
+@arc4.abimethod
+def del_global_state_example(self) -> bool:
+    # Delete multiple values
+    del self.global_bytes_no_default.value
+    del self.global_bool_no_default.value
+    del self.global_asset.value
+    return True
+```
+
+## Value Property Access
+
+```python
+@arc4.abimethod
+def check_global_state_example(self) -> bool:
+    # Direct value access
+    assert self.global_int_full.value == 50
+    assert self.global_bytes_full.value == Bytes(b"Hello")
+    
+    # Simplified syntax access
+    assert self.global_int_simplified == 10
+    assert self.global_bytes_simplified == b"Hello"
+    assert bool(self.global_bool_simplified)
+    
+    # Check existence
+    assert not self.global_int_no_default
+    assert not self.global_bytes_no_default
+    
+    # Special types access
+    assert self.global_asset.value == Asset(UInt64(10))
+    assert self.global_application.value == Application(UInt64(10))
+    assert self.global_account.value == Account(Bytes(b"Hello"))
+    return True
+```
+
+## Best Practices
+
+1. **Initialization**:
+   - Use appropriate types for your data
+   - Consider whether default values are needed
+   - Use simplified syntax when appropriate
+   - Document the purpose of each state variable
+
+2. **Reading State**:
+   - Use `get()` with default values for safe access
+   - Use `maybe()` when you need to check existence
+   - Handle non-existent values gracefully
+   - Verify type consistency
+
+3. **Writing State**:
+   - Validate data before writing
+   - Use appropriate type conversions
+   - Consider storage costs
+   - Update related state consistently
+
+4. **Deleting State**:
+   - Clean up unused state to save storage
+   - Verify deletion success
+   - Handle deletion errors gracefully
+   - Consider impact on related state
+
+5. **Type Safety**:
+   - Use proper type annotations
+   - Verify type compatibility
+   - Handle type conversions explicitly
+   - Test with various data types
+
+6. **Performance**:
+   - Minimize state operations
+   - Use appropriate data structures
+   - Consider storage costs
+   - Optimize state access patterns
+
+This guide demonstrates the various aspects of working with global state in Algorand smart contracts using Python. Understanding these concepts is crucial for developing efficient and reliable smart contracts.