@goplausible/algorand-mcp 3.0.7

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

@@ -0,0 +1,133 @@
+# Hello World Smart Contract
+
+This example demonstrates how to create a basic smart contract using Algorand Python. The contract implements a simple "hello" function that takes a name parameter and returns a greeting.
+
+## Contract Implementation
+
+```python
+from algopy import ARC4Contract, String
+from algopy.arc4 import abimethod
+
+class HelloWorld(ARC4Contract):
+    @abimethod()
+    def hello(self, name: String) -> String:
+        return "Hello, " + name
+```
+
+### Key Components
+
+1. **Imports**:
+   - `ARC4Contract`: Base class for ARC4-compliant smart contracts
+   - `String`: Type for string values in the contract
+   - `abimethod`: Decorator to define ABI-compliant methods
+
+2. **Contract Class**:
+   - Inherits from `ARC4Contract`
+   - Implements a single method `hello`
+   - Uses type hints for parameters and return values
+
+3. **Hello Method**:
+   - Takes a `name` parameter of type `String`
+   - Returns a greeting string concatenating "Hello, " with the provided name
+   - Decorated with `@abimethod()` to make it callable from outside the contract
+
+## Testing the Contract
+
+Here's how to interact with the contract using the AlgoKit Utils Python SDK:
+
+```python
+from algokit_utils import (
+    AlgoAmount,
+    AlgorandClient,
+    OnSchemaBreak,
+    OnUpdate,
+    PaymentParams,
+    SigningAccount,
+)
+from smart_contracts.artifacts.hello_world.hello_world_client import (
+    HelloArgs,
+    HelloWorldClient,
+    HelloWorldFactory,
+)
+
+# Deploy the contract
+factory = algorand.client.get_typed_app_factory(
+    HelloWorldFactory,
+    default_sender=creator.address,
+    default_signer=creator.signer,
+)
+
+client, deploy_result = factory.deploy(
+    on_update=OnUpdate.ReplaceApp,
+    on_schema_break=OnSchemaBreak.Fail,
+)
+
+# Fund the contract with 1 Algo
+algorand.send.payment(
+    PaymentParams(
+        sender=dispenser.address,
+        receiver=client.app_address,
+        amount=AlgoAmount(algo=1),
+    )
+)
+
+# Call the hello method
+result = client.send.hello(HelloArgs(name="World"))
+assert result.abi_return == "Hello, World"
+
+# Simulate multiple calls
+result = (
+    client.new_group()
+    .hello(HelloArgs(name="World"))
+    .hello(HelloArgs(name="Jane"))
+    .simulate()
+)
+```
+
+### Testing Features
+
+1. **Basic Call**:
+   - Create an instance of the contract client
+   - Call the `hello` method with a name argument
+   - Verify the returned greeting
+
+2. **Transaction Group Simulation**:
+   - Create a group of transactions
+   - Call the `hello` method multiple times
+   - Simulate the execution
+   - Verify the results and check the app budget consumption
+
+## Key Concepts
+
+1. **ARC4 Compliance**:
+   - The contract follows the ARC4 standard for method calls
+   - Uses typed parameters and return values
+   - Provides ABI-compatible methods
+
+2. **Contract Deployment**:
+   - Uses `AlgoKit` for deployment
+   - Configures update behavior and schema break handling
+   - Funds the contract with initial Algos
+
+3. **Contract Interaction**:
+   - Uses generated client code for type-safe interactions
+   - Supports both direct calls and transaction group simulations
+   - Provides budget consumption insights
+
+## Best Practices
+
+1. **Type Safety**:
+   - Use proper type hints for parameters and return values
+   - Leverage the generated client code for type-safe interactions
+
+2. **Testing**:
+   - Write comprehensive tests for contract methods
+   - Use simulation to verify behavior before deployment
+   - Check resource consumption through budget metrics
+
+3. **Deployment**:
+   - Configure appropriate update and schema break behaviors
+   - Ensure proper funding for contract operations
+   - Use AlgoKit's deployment utilities for consistency
+
+This Hello World example serves as a foundation for understanding basic smart contract development with Algorand Python. It demonstrates the essential components of contract creation, deployment, and interaction while following best practices for development and testing.

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

@@ -0,0 +1,247 @@
+# Inner Transactions in Algorand Smart Contracts
+
+Inner transactions allow smart contracts to create and submit transactions from within the contract. This guide demonstrates various types of inner transactions in Algorand Python smart contracts.
+
+## Payment Transactions
+
+```python
+from algopy import (
+    Account,
+    Application,
+    ARC4Contract,
+    Asset,
+    Global,
+    String,
+    Txn,
+    UInt64,
+    arc4,
+    itxn,
+)
+
+class InnerTransactions(ARC4Contract):
+    @abimethod()
+    def payment(self) -> UInt64:
+        # Send payment from contract to transaction sender
+        result = itxn.Payment(
+            amount=5000,
+            receiver=Txn.sender,
+            fee=0  # fee is 0 by default, shown here for demonstration
+        ).submit()
+        return result.amount
+```
+
+Note: The sender for inner transactions is implicitly `Global.current_application_address()`.
+
+## Asset Operations
+
+### Creating Assets
+
+```python
+@abimethod
+def fungible_asset_create(self) -> UInt64:
+    # Create a fungible token
+    itxn_result = itxn.AssetConfig(
+        total=100_000_000_000,
+        decimals=2,
+        unit_name="RP",
+        asset_name="Royalty Points",
+    ).submit()
+    return itxn_result.created_asset.id
+
+@abimethod
+def non_fungible_asset_create(self) -> UInt64:
+    # Create an NFT following ARC3 standard
+    itxn_result = itxn.AssetConfig(
+        total=100,
+        decimals=2,
+        unit_name="ML",
+        asset_name="Mona Lisa",
+        url="https://link_to_ipfs/Mona_Lisa",
+        manager=Global.current_application_address,
+        reserve=Global.current_application_address,
+        freeze=Global.current_application_address,
+        clawback=Global.current_application_address,
+    ).submit()
+    return itxn_result.created_asset.id
+```
+
+### Asset Opt-In and Transfer
+
+```python
+@abimethod
+def asset_opt_in(self, asset: Asset) -> None:
+    # Opt-in to an asset
+    itxn.AssetTransfer(
+        asset_receiver=Global.current_application_address,
+        xfer_asset=asset,
+        asset_amount=0,
+        fee=0,
+    ).submit()
+
+@abimethod
+def asset_transfer(self, asset: Asset, receiver: Account, amount: UInt64) -> None:
+    # Transfer assets
+    itxn.AssetTransfer(
+        asset_receiver=receiver,
+        xfer_asset=asset,
+        asset_amount=amount,
+        fee=0,
+    ).submit()
+```
+
+### Asset Management
+
+```python
+@abimethod
+def asset_freeze(self, acct_to_be_frozen: Account, asset: Asset) -> None:
+    # Freeze an account's asset holdings
+    itxn.AssetFreeze(
+        freeze_account=acct_to_be_frozen,
+        freeze_asset=asset,
+        frozen=True,
+        fee=0,
+    ).submit()
+
+@abimethod
+def asset_revoke(
+    self, asset: Asset, account_to_be_revoked: Account, amount: UInt64
+) -> None:
+    # Revoke (clawback) assets from an account
+    itxn.AssetTransfer(
+        asset_receiver=Global.current_application_address,
+        xfer_asset=asset,
+        asset_sender=account_to_be_revoked,
+        asset_amount=amount,
+        fee=0,
+    ).submit()
+
+@abimethod
+def asset_config(self, asset: Asset) -> None:
+    # Reconfigure asset parameters
+    itxn.AssetConfig(
+        config_asset=asset,
+        manager=Global.current_application_address,
+        reserve=Global.current_application_address,
+        freeze=Txn.sender,
+        clawback=Txn.sender,
+        fee=0,
+    ).submit()
+
+@abimethod
+def asset_delete(self, asset: Asset) -> None:
+    # Delete an asset
+    itxn.AssetConfig(
+        config_asset=asset,
+        fee=0,
+    ).submit()
+```
+
+## Application Operations
+
+### Grouped Inner Transactions
+
+```python
+@abimethod
+def multi_inner_txns(self, app_id: Application) -> tuple[UInt64, arc4.String]:
+    # Create payment transaction
+    payment_params = itxn.Payment(amount=5000, receiver=Txn.sender, fee=0)
+
+    # Create application call transaction
+    app_call_params = itxn.ApplicationCall(
+        app_id=app_id,
+        app_args=(arc4.arc4_signature("hello(string)string"), arc4.String("World")),
+        fee=0,
+    )
+
+    # Submit both transactions atomically
+    pay_txn, app_call_txn = itxn.submit_txns(payment_params, app_call_params)
+
+    # Process results
+    hello_world_result = arc4.String.from_log(app_call_txn.last_log)
+    return pay_txn.amount, hello_world_result
+```
+
+### Deploying Applications
+
+```python
+@abimethod
+def deploy_app(self) -> UInt64:
+    # Compile and deploy a contract
+    compiled_contract = compile_contract(HelloWorld)
+
+    app_txn = itxn.ApplicationCall(
+        approval_program=compiled_contract.approval_program,
+        clear_state_program=compiled_contract.clear_state_program,
+        fee=0,
+    ).submit()
+    
+    return app_txn.created_app.id
+
+@abimethod
+def arc4_deploy_app(self) -> UInt64:
+    # Deploy using ARC4
+    app_txn = arc4.arc4_create(HelloWorld)
+    return app_txn.created_app.id
+```
+
+### Application Calls
+
+```python
+@abimethod
+def noop_app_call(self, app_id: Application) -> tuple[arc4.String, String]:
+    # Method 1: Manual ABI encoding
+    call_txn = itxn.ApplicationCall(
+        app_id=app_id,
+        app_args=(arc4.arc4_signature("hello(string)string"), arc4.String("World")),
+    ).submit()
+    first_result = arc4.String.from_log(call_txn.last_log)
+
+    # Method 2: Automatic ARC4 encoding
+    second_result, call_txn = arc4.abi_call(
+        HelloWorld.hello,  # method signature
+        "again",          # arguments
+        app_id=app_id,
+    )
+
+    return first_result, second_result
+```
+
+## Best Practices
+
+1. **Transaction Management**:
+   - Use appropriate fee settings
+   - Handle transaction failures gracefully
+   - Group related transactions when needed
+   - Verify transaction results
+
+2. **Asset Operations**:
+   - Verify asset configuration before operations
+   - Handle opt-in requirements
+   - Manage asset permissions carefully
+   - Validate asset amounts and balances
+
+3. **Application Deployment**:
+   - Use appropriate deployment method
+   - Verify contract compilation
+   - Handle deployment failures
+   - Test deployed applications
+
+4. **Security**:
+   - Validate transaction parameters
+   - Check permissions and authorizations
+   - Handle edge cases and errors
+   - Implement proper access controls
+
+5. **Performance**:
+   - Minimize number of inner transactions
+   - Group transactions when possible
+   - Consider fee implications
+   - Optimize transaction parameters
+
+6. **Error Handling**:
+   - Check transaction success
+   - Handle failed transactions
+   - Provide meaningful error messages
+   - Implement proper rollback mechanisms
+
+This guide demonstrates the various capabilities of inner transactions in Algorand smart contracts using Python. Understanding these concepts is crucial for developing complex smart contract interactions.

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

@@ -0,0 +1,227 @@
+# Local Storage in Algorand Smart Contracts
+
+Local storage in Algorand smart contracts allows you to store per-account state data. This guide demonstrates how to work with local storage using Python.
+
+## Initializing Local Storage
+
+```python
+from algopy import (
+    Account,
+    Application,
+    ARC4Contract,
+    Asset,
+    Bytes,
+    LocalState,
+    UInt64,
+    arc4,
+)
+
+class LocalStorage(ARC4Contract):
+    def __init__(self) -> None:
+        # Initialize different types of local storage
+        self.local_int = LocalState(UInt64)           # Integer storage
+        self.local_bytes = LocalState(Bytes)          # Bytes storage
+        self.local_bool = LocalState(bool)            # Boolean storage
+        self.local_asset = LocalState(Asset)          # Asset reference
+        self.local_application = LocalState(Application)  # Application reference
+        self.local_account = LocalState(Account)      # Account reference
+```
+
+## Reading Local State
+
+### Basic Access
+
+```python
+@arc4.abimethod
+def get_item_local_data(self, for_account: Account) -> UInt64:
+    # Direct access using indexing
+    return self.local_int[for_account]
+
+@arc4.abimethod
+def get_local_data_with_default_int(self, for_account: Account) -> UInt64:
+    # Access with default value
+    return self.local_int.get(for_account, default=UInt64(0))
+
+@arc4.abimethod
+def maybe_local_data(self, for_account: Account) -> tuple[UInt64, bool]:
+    # Get value and existence flag
+    result, exists = self.local_int.maybe(for_account)
+    if not exists:
+        result = UInt64(0)
+    return result, exists
+```
+
+### Reading Different Types
+
+```python
+@arc4.abimethod
+def get_item_local_data_example(self, for_account: Account) -> bool:
+    # Reading integers
+    assert self.local_int[for_account] == UInt64(10)
+    
+    # Reading bytes
+    assert self.local_bytes[for_account] == b"Hello"
+    
+    # Reading booleans
+    assert bool(self.local_bool[for_account])
+    
+    # Reading special types
+    assert self.local_asset[for_account] == Asset(UInt64(10))
+    assert self.local_application[for_account] == Application(UInt64(10))
+    assert self.local_account[for_account] == Account(Bytes(b"Hello"))
+    return True
+```
+
+### Reading with Default Values
+
+```python
+@arc4.abimethod
+def get_local_data_with_default(self, for_account: Account) -> bool:
+    # Integer with default
+    assert self.local_int.get(for_account, default=UInt64(0)) == UInt64(10)
+    
+    # Bytes with default
+    assert self.local_bytes.get(
+        for_account, 
+        default=Bytes(b"Default Value")
+    ) == Bytes(b"Hello")
+    
+    # Boolean with default
+    assert bool(self.local_bool.get(for_account, default=False))
+    
+    # Asset with default
+    assert self.local_asset.get(
+        for_account, 
+        default=Asset(UInt64(0))
+    ) == Asset(UInt64(10))
+    
+    return True
+```
+
+## Writing Local State
+
+### Basic Writing
+
+```python
+@arc4.abimethod
+def set_local_int(self, for_account: Account, value: UInt64) -> None:
+    # Set integer value for account
+    self.local_int[for_account] = value
+```
+
+### Writing Different Types
+
+```python
+@arc4.abimethod
+def set_local_data_example(
+    self,
+    for_account: Account,
+    value_asset: Asset,
+    value_account: Account,
+    value_appln: Application,
+    value_byte: Bytes,
+    *,
+    value_bool: bool,
+) -> bool:
+    # Set bytes
+    self.local_bytes[for_account] = value_byte
+    
+    # Set boolean
+    self.local_bool[for_account] = value_bool
+    
+    # Set asset reference
+    self.local_asset[for_account] = value_asset
+    
+    # Set application reference
+    self.local_application[for_account] = value_appln
+    
+    # Set account reference
+    self.local_account[for_account] = value_account
+    
+    # Verify values
+    assert self.local_bytes[for_account] == value_byte
+    assert self.local_bool[for_account] == value_bool
+    assert self.local_asset[for_account] == value_asset
+    return True
+```
+
+## Checking State Existence
+
+```python
+@arc4.abimethod
+def contains_local_data(self, for_account: Account) -> bool:
+    # Check if account has local state
+    assert for_account in self.local_int
+    return True
+
+@arc4.abimethod
+def contains_local_data_example(self, for_account: Account) -> bool:
+    # Check existence for all types
+    assert for_account in self.local_int
+    assert for_account in self.local_bytes
+    assert for_account in self.local_bool
+    assert for_account in self.local_asset
+    assert for_account in self.local_application
+    assert for_account in self.local_account
+    return True
+```
+
+## Deleting Local State
+
+```python
+@arc4.abimethod
+def delete_local_data(self, for_account: Account) -> None:
+    # Delete single value
+    del self.local_account[for_account]
+
+@arc4.abimethod
+def delete_local_data_example(self, for_account: Account) -> bool:
+    # Delete all types of local state
+    del self.local_int[for_account]
+    del self.local_bytes[for_account]
+    del self.local_bool[for_account]
+    del self.local_asset[for_account]
+    del self.local_application[for_account]
+    del self.local_account[for_account]
+    return True
+```
+
+## Best Practices
+
+1. **Initialization**:
+   - Use appropriate types for your data
+   - Initialize all required state variables
+   - Document state variable purposes
+   - Consider storage limits
+
+2. **Reading State**:
+   - Use `get()` with default values for safe access
+   - Use `maybe()` when existence check is needed
+   - 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. **State Existence**:
+   - Check state existence before access
+   - Handle missing state gracefully
+   - Use appropriate default values
+   - Consider opt-in requirements
+
+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 local state in Algorand smart contracts using Python. Understanding these concepts is crucial for developing applications that need to maintain per-account state.