@goplausible/algorand-mcp 3.0.7

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

@@ -0,0 +1,169 @@
+# Scratch Storage in Algorand Smart Contracts
+
+This guide demonstrates how to use scratch storage in Algorand smart contracts. Scratch storage provides temporary storage slots that can be used during contract execution.
+
+## Basic Implementation
+
+```python
+from algopy import ARC4Contract, Bytes, Contract, UInt64, op, urange
+from algopy.arc4 import abimethod
+
+TWO = 2
+TWENTY = 20
+
+class ScratchSlotsContract(ARC4Contract, scratch_slots=(1, TWO, urange(3, TWENTY))):
+    @abimethod
+    def store_data(self) -> bool:
+        # Store values in scratch slots
+        op.Scratch.store(1, UInt64(5))
+        op.Scratch.store(2, Bytes(b"Hello World"))
+        
+        # Load and verify values
+        assert op.Scratch.load_uint64(1) == UInt64(5)
+        assert op.Scratch.load_bytes(2) == b"Hello World"
+        return True
+```
+
+## Simplified Contract Example
+
+```python
+class SimpleScratchSlotsContract(Contract, scratch_slots=(1, TWO, urange(3, TWENTY))):
+    def approval_program(self) -> UInt64:
+        # Load and verify values from scratch storage
+        assert op.Scratch.load_uint64(1) == UInt64(5)
+        assert op.Scratch.load_bytes(2) == b"Hello World"
+        return UInt64(1)
+
+    def clear_state_program(self) -> UInt64:
+        return UInt64(1)
+```
+
+## Key Features
+
+### Scratch Slots Declaration
+
+```python
+# Define scratch slots in class definition
+scratch_slots=(1, TWO, urange(3, TWENTY))
+```
+- Specify individual slots (1)
+- Use constants (TWO)
+- Define ranges (urange(3, TWENTY))
+
+### Storage Operations
+
+```python
+# Store values
+op.Scratch.store(1, UInt64(5))          # Store integer
+op.Scratch.store(2, Bytes(b"Hello"))    # Store bytes
+
+# Load values
+value1 = op.Scratch.load_uint64(1)      # Load integer
+value2 = op.Scratch.load_bytes(2)       # Load bytes
+```
+
+## Best Practices
+
+1. **Slot Management**:
+   - Define slots explicitly
+   - Use meaningful constants
+   - Document slot usage
+   - Avoid slot conflicts
+
+2. **Data Types**:
+   - Use appropriate load methods
+   - Verify data types
+   - Handle type conversions
+   - Check value ranges
+
+3. **Memory Usage**:
+   - Minimize slot usage
+   - Clean up after use
+   - Monitor memory limits
+   - Optimize storage
+
+4. **Error Handling**:
+   - Verify loaded values
+   - Handle missing data
+   - Check slot bounds
+   - Validate data types
+
+## Common Patterns
+
+1. **Temporary Calculations**:
+```python
+def calculate_total(self) -> UInt64:
+    # Store intermediate results
+    op.Scratch.store(1, UInt64(5))
+    op.Scratch.store(2, UInt64(10))
+    
+    # Load and combine results
+    value1 = op.Scratch.load_uint64(1)
+    value2 = op.Scratch.load_uint64(2)
+    return value1 + value2
+```
+
+2. **Data Validation**:
+```python
+def validate_input(self, input_data: Bytes) -> bool:
+    # Store input for validation
+    op.Scratch.store(1, input_data)
+    
+    # Load and validate
+    stored_data = op.Scratch.load_bytes(1)
+    return stored_data == input_data
+```
+
+## Technical Details
+
+1. **Slot Allocation**:
+   - Slots are numbered from 0
+   - Maximum slot number is 255
+   - Each slot can store any type
+   - Slots are cleared after execution
+
+2. **Data Types**:
+   - UInt64 for integers
+   - Bytes for byte strings
+   - Type-specific load methods
+   - Automatic type checking
+
+3. **Memory Constraints**:
+   - Limited number of slots
+   - Temporary storage only
+   - No persistence between calls
+   - Efficient for calculations
+
+4. **Performance**:
+   - Fast access times
+   - Low overhead
+   - Efficient for loops
+   - Good for temporary data
+
+## Use Cases
+
+1. **Complex Calculations**:
+   - Store intermediate results
+   - Break down computations
+   - Reuse common values
+   - Optimize performance
+
+2. **Data Validation**:
+   - Store input data
+   - Compare values
+   - Check constraints
+   - Verify formats
+
+3. **State Transitions**:
+   - Store previous state
+   - Calculate changes
+   - Verify transitions
+   - Update final state
+
+4. **Loop Operations**:
+   - Store counters
+   - Accumulate results
+   - Track iterations
+   - Handle aggregations
+
+This guide demonstrates how to effectively use scratch storage in Algorand smart contracts. Understanding scratch storage is crucial for optimizing contract performance and managing temporary data during execution.

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

@@ -0,0 +1,167 @@
+# Self Payment Logic Signatures in Algorand
+
+This guide demonstrates how to implement a self-payment logic signature (LogicSig) in Algorand using Python. A self-payment LogicSig allows an account to make payments to itself under specific conditions.
+
+## Self Payment Implementation
+
+```python
+from algopy import (
+    Bytes,
+    Global,
+    TemplateVar,
+    TransactionType,
+    Txn,
+    UInt64,
+    logicsig,
+    op,
+)
+
+@logicsig
+def self_payment() -> bool:
+    """
+    This Delegated Account will authorize a single empty self payment 
+    in a block known ahead of time.
+    """
+    return (
+        # Verify transaction type is Payment
+        Txn.type_enum == TransactionType.Payment
+        # Ensure receiver is the same as sender
+        and Txn.receiver == Txn.sender
+        # Ensure payment amount is 0
+        and Txn.amount == 0
+        # Prevent account rekeying
+        and Txn.rekey_to == Global.zero_address
+        # Prevent account closure
+        and Txn.close_remainder_to == Global.zero_address
+        # Ensure minimum transaction fee
+        and Txn.fee == Global.min_txn_fee
+        # Verify network by genesis hash
+        and Global.genesis_hash == TemplateVar[Bytes]("TARGET_NETWORK_GENESIS")
+        # Prevent replay attacks with round number
+        and Txn.last_valid == TemplateVar[UInt64]("LAST_ROUND")
+        # Use lease to prevent concurrent transactions
+        and Txn.lease == op.sha256(b"self-payment")
+    )
+```
+
+## Key Components
+
+### Transaction Validation
+
+1. **Payment Type**:
+   ```python
+   Txn.type_enum == TransactionType.Payment
+   ```
+   - Ensures the transaction is a payment transaction
+   - Rejects any other transaction types
+
+2. **Self Payment**:
+   ```python
+   Txn.receiver == Txn.sender
+   ```
+   - Verifies that the receiver is the same as the sender
+   - Ensures funds stay within the same account
+
+3. **Zero Amount**:
+   ```python
+   Txn.amount == 0
+   ```
+   - Ensures the payment amount is zero
+   - Prevents accidental fund transfers
+
+### Security Measures
+
+1. **Rekey Prevention**:
+   ```python
+   Txn.rekey_to == Global.zero_address
+   ```
+   - Prevents account rekeying
+   - Maintains account control
+
+2. **Closure Prevention**:
+   ```python
+   Txn.close_remainder_to == Global.zero_address
+   ```
+   - Prevents account closure
+   - Protects account funds
+
+3. **Fee Control**:
+   ```python
+   Txn.fee == Global.min_txn_fee
+   ```
+   - Ensures minimum transaction fee
+   - Prevents fee manipulation
+
+### Replay Protection
+
+1. **Network Verification**:
+   ```python
+   Global.genesis_hash == TemplateVar[Bytes]("TARGET_NETWORK_GENESIS")
+   ```
+   - Verifies the correct network
+   - Prevents cross-network replay attacks
+
+2. **Round Number Check**:
+   ```python
+   Txn.last_valid == TemplateVar[UInt64]("LAST_ROUND")
+   ```
+   - Enforces specific round number
+   - Limits transaction validity period
+
+3. **Transaction Lease**:
+   ```python
+   Txn.lease == op.sha256(b"self-payment")
+   ```
+   - Prevents concurrent transactions
+   - Adds additional replay protection
+
+## Use Cases
+
+1. **Account Maintenance**:
+   - Regular account activity
+   - Keeping account active
+   - Preventing account dormancy
+
+2. **Network Participation**:
+   - Maintaining network presence
+   - Participating in consensus
+   - Meeting activity requirements
+
+3. **Security Verification**:
+   - Account control verification
+   - Network connectivity testing
+   - Transaction capability testing
+
+## Best Practices
+
+1. **Transaction Parameters**:
+   - Always use zero amount for self-payments
+   - Set appropriate transaction fees
+   - Use minimum required parameters
+
+2. **Security**:
+   - Implement all security checks
+   - Use replay protection mechanisms
+   - Verify network parameters
+
+3. **Round Numbers**:
+   - Choose appropriate round numbers
+   - Consider network timing
+   - Account for block finality
+
+4. **Lease Management**:
+   - Use unique lease values
+   - Implement proper lease timing
+   - Handle lease expiration
+
+5. **Error Handling**:
+   - Validate all parameters
+   - Handle failure cases
+   - Provide clear error messages
+
+6. **Testing**:
+   - Test on test networks first
+   - Verify all security measures
+   - Simulate various scenarios
+
+This guide demonstrates how to implement a secure self-payment logic signature in Algorand using Python. The implementation includes various security measures to prevent unauthorized use and replay attacks while ensuring the transaction serves its intended purpose.

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

@@ -0,0 +1,182 @@
+# Structs in Box Storage for Algorand Smart Contracts
+
+This guide demonstrates how to use structs with box storage in Algorand smart contracts using Python. Box storage with structs provides a way to store complex data structures efficiently.
+
+## Defining a Struct
+
+```python
+from algopy import BoxMap, arc4
+
+class UserStruct(arc4.Struct):
+    name: arc4.String
+    id: arc4.UInt64
+    asset: arc4.UInt64
+```
+
+The struct definition includes:
+- Type annotations for each field
+- ARC4-compatible data types
+- Clear field naming
+
+## Implementing Box Storage with Structs
+
+```python
+class StructInBoxMap(arc4.ARC4Contract):
+    def __init__(self) -> None:
+        # Initialize box map with UInt64 keys and UserStruct values
+        self.user_map = BoxMap(
+            arc4.UInt64,        # Key type
+            UserStruct,         # Value type
+            key_prefix="users"  # Optional prefix for organization
+        )
+```
+
+## Basic Operations
+
+### Setting Values
+
+```python
+@arc4.abimethod
+def box_map_set(self, key: arc4.UInt64, value: UserStruct) -> bool:
+    # Always use copy() when storing structs
+    self.user_map[key] = value.copy()
+    
+    # Verify storage
+    assert self.user_map[key] == value
+    return True
+
+@arc4.abimethod
+def box_map_test(self) -> bool:
+    key_0 = arc4.UInt64(0)
+    
+    # Create struct instance
+    value = UserStruct(
+        arc4.String("testName"),
+        arc4.UInt64(70),
+        arc4.UInt64(2)
+    )
+
+    # Store and verify
+    self.user_map[key_0] = value.copy()
+    
+    # Verify byte length
+    assert self.user_map[key_0].bytes.length == value.bytes.length
+    assert self.user_map.length(key_0) == value.bytes.length
+    return True
+```
+
+### Getting Values
+
+```python
+@arc4.abimethod
+def box_map_get(self, key: arc4.UInt64) -> UserStruct:
+    # Retrieve struct from box storage
+    return self.user_map[key]
+```
+
+### Checking Existence
+
+```python
+@arc4.abimethod
+def box_map_exists(self, key: arc4.UInt64) -> bool:
+    # Check if key exists in box map
+    return key in self.user_map
+```
+
+## Usage Examples
+
+### Creating and Storing a User
+
+```python
+# Create user struct
+user = UserStruct(
+    name=arc4.String("Alice"),
+    id=arc4.UInt64(1),
+    asset=arc4.UInt64(100)
+)
+
+# Store in box map
+key = arc4.UInt64(1)
+box_map_set(key, user)
+```
+
+### Retrieving User Data
+
+```python
+# Get user by key
+key = arc4.UInt64(1)
+user = box_map_get(key)
+
+# Access struct fields
+name = user.name      # arc4.String
+user_id = user.id     # arc4.UInt64
+asset = user.asset    # arc4.UInt64
+```
+
+## Best Practices
+
+1. **Struct Design**:
+   - Use appropriate field types
+   - Keep structs focused and organized
+   - Consider field order for efficiency
+   - Document struct purpose and usage
+
+2. **Data Management**:
+   - Always use copy() when storing structs
+   - Verify stored data after writing
+   - Check existence before reading
+   - Handle missing data gracefully
+
+3. **Storage Efficiency**:
+   - Consider struct size limitations
+   - Use appropriate key prefixes
+   - Clean up unused storage
+   - Monitor storage usage
+
+4. **Type Safety**:
+   - Use proper type annotations
+   - Verify field types
+   - Handle type conversions carefully
+   - Test with various data types
+
+5. **Error Handling**:
+   - Check for missing keys
+   - Validate struct data
+   - Handle storage errors
+   - Provide clear error messages
+
+6. **Performance**:
+   - Minimize storage operations
+   - Use efficient data structures
+   - Consider storage costs
+   - Optimize access patterns
+
+## Common Patterns
+
+1. **User Data Storage**:
+```python
+user = UserStruct(
+    arc4.String("username"),
+    arc4.UInt64(user_id),
+    arc4.UInt64(balance)
+)
+```
+
+2. **Batch Operations**:
+```python
+def update_multiple_users(self, users: list[UserStruct]) -> None:
+    for i, user in enumerate(users):
+        self.user_map[arc4.UInt64(i)] = user.copy()
+```
+
+3. **Data Validation**:
+```python
+def validate_user(self, user: UserStruct) -> bool:
+    return (
+        user.name.native != ""
+        and user.id.native > 0
+        and user.asset.native >= 0
+    )
+```
+
+This guide demonstrates how to effectively use structs with box storage in Algorand smart contracts. Understanding these concepts is crucial for developing applications that need to store and manage complex data structures efficiently.

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

@@ -0,0 +1,189 @@
+# Subsidizing Application Calls in Algorand
+
+This guide demonstrates how to implement a logic signature (LogicSig) that subsidizes application calls in Algorand smart contracts. This allows a contract account to pay the transaction fees for application calls to a specific application.
+
+## Implementation
+
+```python
+from algopy import (
+    Application,
+    Bytes,
+    Global,
+    TemplateVar,
+    TransactionType,
+    Txn,
+    UInt64,
+    logicsig,
+)
+from algopy.op import GTxn
+
+@logicsig
+def subsidize_app_call() -> bool:
+    """
+    This Contract Account will subsidize the fees for any AppCall 
+    transaction directed to a known application.
+    """
+    return (
+        # Payment Transaction Validation
+        Txn.type_enum == TransactionType.Payment
+        and Txn.receiver == Txn.sender
+        and Txn.amount == 0
+        and Txn.rekey_to == Global.zero_address
+        and Txn.close_remainder_to == Global.zero_address
+        and Txn.fee == 2 * Global.min_txn_fee
+        and Txn.last_valid <= TemplateVar[UInt64]("EXPIRATION_ROUND")
+        and Global.genesis_hash == TemplateVar[Bytes]("TARGET_NETWORK_GENESIS")
+        # Application Call Validation
+        and GTxn.type_enum(Txn.group_index - 1) == TransactionType.ApplicationCall
+        and GTxn.application_id(Txn.group_index - 1) == TemplateVar[Application]("KNOWN_APP")
+        and GTxn.fee(Txn.group_index - 1) == 0
+    )
+```
+
+## Key Components
+
+### Payment Transaction Validation
+
+1. **Transaction Type**:
+   ```python
+   Txn.type_enum == TransactionType.Payment
+   ```
+   - Ensures the transaction is a payment type
+   - Required for fee subsidization
+
+2. **Self Payment**:
+   ```python
+   Txn.receiver == Txn.sender
+   and Txn.amount == 0
+   ```
+   - Verifies transaction is to self
+   - Ensures no funds are transferred
+
+3. **Security Measures**:
+   ```python
+   Txn.rekey_to == Global.zero_address
+   and Txn.close_remainder_to == Global.zero_address
+   ```
+   - Prevents account rekeying
+   - Prevents account closure
+
+4. **Fee Structure**:
+   ```python
+   Txn.fee == 2 * Global.min_txn_fee
+   ```
+   - Sets fee to cover both transactions
+   - Uses minimum transaction fee as base
+
+### Application Call Validation
+
+1. **Previous Transaction Check**:
+   ```python
+   GTxn.type_enum(Txn.group_index - 1) == TransactionType.ApplicationCall
+   ```
+   - Verifies previous transaction is app call
+   - Uses group transaction index
+
+2. **Application Verification**:
+   ```python
+   GTxn.application_id(Txn.group_index - 1) == TemplateVar[Application]("KNOWN_APP")
+   ```
+   - Validates target application
+   - Uses template variable for flexibility
+
+3. **Fee Verification**:
+   ```python
+   GTxn.fee(Txn.group_index - 1) == 0
+   ```
+   - Ensures app call has zero fee
+   - Required for subsidization
+
+### Time and Network Controls
+
+1. **Expiration Control**:
+   ```python
+   Txn.last_valid <= TemplateVar[UInt64]("EXPIRATION_ROUND")
+   ```
+   - Sets transaction validity period
+   - Prevents indefinite usage
+
+2. **Network Verification**:
+   ```python
+   Global.genesis_hash == TemplateVar[Bytes]("TARGET_NETWORK_GENESIS")
+   ```
+   - Ensures correct network
+   - Prevents cross-network usage
+
+## Usage Pattern
+
+1. **Create Transaction Group**:
+   ```python
+   # First transaction: Application call with zero fee
+   app_call_txn = ApplicationCallTxn(
+       sender=user_address,
+       app_id=known_app_id,
+       fee=0
+   )
+
+   # Second transaction: Payment for fees
+   payment_txn = PaymentTxn(
+       sender=subsidy_address,
+       receiver=subsidy_address,
+       amt=0,
+       fee=2 * min_fee
+   )
+
+   # Group transactions
+   grouped_txns = assign_group_id([app_call_txn, payment_txn])
+   ```
+
+2. **Sign and Submit**:
+   ```python
+   # Sign application call with user's key
+   signed_app_call = app_call_txn.sign(user_private_key)
+
+   # Sign payment with logic signature
+   signed_payment = LogicSigTransaction(payment_txn, logic_sig)
+
+   # Submit group
+   txid = algod_client.send_transactions([signed_app_call, signed_payment])
+   ```
+
+## Best Practices
+
+1. **Security**:
+   - Validate all transaction parameters
+   - Use appropriate template variables
+   - Implement proper access controls
+   - Monitor subsidy account balance
+
+2. **Fee Management**:
+   - Calculate fees correctly
+   - Consider network congestion
+   - Monitor fee changes
+   - Handle fee updates
+
+3. **Application Control**:
+   - Verify application IDs
+   - Limit subsidized applications
+   - Monitor application usage
+   - Track subsidization costs
+
+4. **Time Management**:
+   - Set appropriate expiration rounds
+   - Consider network timing
+   - Handle round transitions
+   - Update expiration as needed
+
+5. **Error Handling**:
+   - Validate all parameters
+   - Handle rejection cases
+   - Provide clear error messages
+   - Monitor failed transactions
+
+6. **Monitoring**:
+   - Track usage patterns
+   - Monitor account balance
+   - Log subsidized calls
+   - Analyze cost metrics
+
+This guide demonstrates how to implement a logic signature for subsidizing application calls in Algorand. The implementation includes security measures, fee management, and proper validation to ensure safe and efficient operation.