@goplausible/algorand-mcp 3.0.7

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

@@ -0,0 +1,215 @@
+# Algorand Account Management with Python
+
+This guide covers various aspects of account management in Algorand using Python, including creating accounts, funding them, managing keys and signatures, working with multisignature accounts, and account rekeying.
+
+## Creating Accounts
+
+There are several ways to create or access Algorand accounts:
+
+```python
+from algokit_utils import AlgorandClient
+
+# Initialize client for LocalNet
+algorand_client = AlgorandClient.default_localnet()
+
+# Create a random account
+random_account = algorand_client.account.random()
+
+# Get or create an account from KMD
+kmd_account = algorand_client.account.from_kmd(name="ACCOUNT_NAME")
+
+# Get or create an account from environment variables
+env_account = algorand_client.account.from_environment(
+    name="MY_ACCOUNT",
+    fund_with=AlgoAmount(algo=10)
+)
+
+# Create an account from mnemonic
+mnemonic_account = algorand_client.account.from_mnemonic(mnemonic="MNEMONIC_PHRASE")
+```
+
+### KMD Wallet Operations
+
+```python
+# Create a new wallet
+algorand_client.client.kmd.create_wallet(name="ACCOUNT_NAME", pswd="password")
+
+# Rename a wallet
+algorand_client.client.kmd.rename_wallet(
+    id="WALLET_ID",
+    password="new_password",
+    new_name="NEW_ACCOUNT_NAME"
+)
+```
+
+## Funding Accounts
+
+### LocalNet Funding
+
+```python
+# Get LocalNet dispenser account
+localnet_dispenser = algorand_client.account.localnet_dispenser()
+
+# Get dispenser account from environment
+dispenser = algorand_client.account.dispenser_from_environment()
+
+# Send payment from dispenser
+algorand_client.send.payment(
+    PaymentParams(
+        sender=localnet_dispenser.address,
+        receiver=random_account.address,
+        amount=AlgoAmount(algo=10)
+    )
+)
+
+# Ensure account has minimum balance
+algorand_client.account.ensure_funded(
+    account_to_fund=random_account.address,
+    dispenser_account=localnet_dispenser.address,
+    min_spending_balance=AlgoAmount(algo=10)
+)
+```
+
+### TestNet Funding
+
+```python
+# Get TestNet dispenser
+testnet_dispenser = algorand_client.client.get_testnet_dispenser()
+
+# Fund using TestNet dispenser API
+algorand_client.account.ensure_funded_from_testnet_dispenser_api(
+    account_to_fund=random_account.address,
+    dispenser_client=testnet_dispenser,
+    min_spending_balance=AlgoAmount(algo=10)
+)
+
+# Direct funding using TestNet dispenser
+testnet_dispenser.fund(address=random_account.address, amount=10, asset_id=0)
+```
+
+## Keys and Signing
+
+### Managing Transaction Signers
+
+```python
+# Set default signer
+algorand_client.account.set_default_signer(account_a.signer)
+
+# Register multiple signers
+algorand_client.account.set_signer_from_account(account_a)
+algorand_client.account.set_signer_from_account(account_b)
+algorand_client.account.set_signer_from_account(account_c)
+
+# Get signer for an address
+signer = algorand_client.account.get_signer(account_a.address)
+```
+
+### Manual Transaction Signing
+
+```python
+# Create unsigned transaction
+payment_txn = algorand_client.create_transaction.payment(
+    PaymentParams(
+        sender=account_a.address,
+        receiver=account_b.address,
+        amount=AlgoAmount(algo=1),
+        note=b"Payment from A to B"
+    )
+)
+
+# Send with custom signer
+algorand_client.new_group().add_transaction(
+    transaction=payment_txn,
+    signer=account_a_signer
+).send()
+```
+
+## Multisignature Accounts
+
+Create and use multisig accounts that require multiple signatures:
+
+```python
+# Create 2-of-3 multisig account
+multisig_account = algorand_client.account.multisig(
+    metadata=MultisigMetadata(
+        version=1,
+        threshold=2,
+        addresses=[
+            account_a.address,
+            account_b.address,
+            account_c.address
+        ]
+    ),
+    signing_accounts=[account_a, account_b, account_c]
+)
+
+# Send from multisig account
+algorand_client.send.payment(
+    PaymentParams(
+        sender=multisig_account.address,
+        receiver=account_a.address,
+        amount=AlgoAmount(algo=1)
+    )
+)
+```
+
+## Account Rekeying
+
+Rekey an account to use a different address for signing:
+
+```python
+# Rekey account_a to be controlled by account_b's private key
+algorand_client.account.rekey_account(
+    account=account_a.address,
+    rekey_to=account_b
+)
+
+# Send transaction using new signing key
+payment_txn = algorand_client.create_transaction.payment(
+    PaymentParams(
+        sender=account_a.address,
+        receiver=account_b.address,
+        amount=AlgoAmount(algo=1),
+        signer=account_b.signer
+    )
+)
+
+algorand_client.new_group().add_transaction(
+    transaction=payment_txn,
+    signer=account_b.signer
+).send()
+```
+
+## Best Practices
+
+1. **Account Creation**:
+   - Use environment variables for sensitive information
+   - Store mnemonics securely
+   - Use KMD for development and testing
+
+2. **Account Funding**:
+   - Always ensure accounts have sufficient minimum balance
+   - Use appropriate funding methods for different networks (LocalNet, TestNet)
+   - Handle funding errors gracefully
+
+3. **Transaction Signing**:
+   - Set up default signers for convenience
+   - Use explicit signers for critical operations
+   - Verify transaction parameters before signing
+
+4. **Multisig Accounts**:
+   - Choose appropriate threshold values
+   - Keep track of all signing accounts
+   - Test multisig operations thoroughly
+
+5. **Account Rekeying**:
+   - Document rekeying operations
+   - Maintain secure backup of original keys
+   - Verify rekeying success before proceeding
+
+6. **Security**:
+   - Never expose private keys or mnemonics
+   - Use secure methods for key storage
+   - Implement proper access controls
+
+This guide provides a comprehensive overview of account management in Algorand using Python. The examples demonstrate the flexibility and security features available through the Algorand Python SDK and AlgoKit utilities.

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

@@ -0,0 +1,267 @@
+# ARC4 Types in Algorand Smart Contracts
+
+This guide covers the various ARC4 data types available in Algorand smart contracts using Python, including integers, arrays, bytes, addresses, structs, and tuples.
+
+## Integer Types
+
+### Basic Integer Types
+
+```python
+from algopy import ARC4Contract, UInt64, arc4
+
+class Arc4Types(ARC4Contract):
+    @abimethod()
+    def add_arc4_uint64(self, a: arc4.UInt64, b: arc4.UInt64) -> arc4.UInt64:
+        # Use .native for arithmetic operations
+        c = a.native + b.native
+        return arc4.UInt64(c)
+```
+
+### Different Integer Sizes
+
+```python
+@abimethod()
+def add_arc4_uint_n(
+    self, a: arc4.UInt8, b: arc4.UInt16, c: arc4.UInt32, d: arc4.UInt64
+) -> arc4.UInt64:
+    # Different integer sizes have different byte lengths
+    assert a.bytes.length == 1  # UInt8 = 1 byte
+    assert b.bytes.length == 2  # UInt16 = 2 bytes
+    assert c.bytes.length == 4  # UInt32 = 4 bytes
+    assert d.bytes.length == 8  # UInt64 = 8 bytes
+
+    total = a.native + b.native + c.native + d.native
+    return arc4.UInt64(total)
+```
+
+### Big Integers
+
+```python
+@abimethod()
+def add_arc4_biguint_n(
+    self, a: arc4.UInt128, b: arc4.UInt256, c: arc4.UInt512
+) -> arc4.UInt512:
+    # Support for larger integers up to 512 bits
+    assert a.bytes.length == 16  # 128 bits
+    assert b.bytes.length == 32  # 256 bits
+    assert c.bytes.length == 64  # 512 bits
+
+    total = a.native + b.native + c.native
+    return arc4.UInt512(total)
+```
+
+## Bytes and Address Types
+
+### Bytes
+
+```python
+@abimethod()
+def arc4_byte(self, a: arc4.Byte) -> arc4.Byte:
+    # arc4.Byte is an 8-bit integer
+    return arc4.Byte(a.native + 1)
+```
+
+### Addresses
+
+```python
+@abimethod()
+def arc4_address_properties(self, address: arc4.Address) -> UInt64:
+    # Access address properties
+    underlying_bytes = address.bytes
+    account = address.native  # Get account type
+
+    bal = account.balance
+    total_asset = account.total_assets
+
+    return bal
+
+@abimethod()
+def arc4_address_return(self, address: arc4.Address) -> arc4.Address:
+    # Convert Account type to Address
+    account = address.native
+    converted_address = arc4.Address(account)
+    return converted_address
+```
+
+## Arrays
+
+### Static Arrays
+
+```python
+import typing as t
+
+# Define a static array type alias
+AliasedStaticArray: t.TypeAlias = arc4.StaticArray[arc4.UInt8, t.Literal[1]]
+
+class Arc4StaticArray(ARC4Contract):
+    @abimethod()
+    def arc4_static_array(self) -> None:
+        # Create static array directly
+        static_uint32_array = arc4.StaticArray(
+            arc4.UInt32(1), arc4.UInt32(10), 
+            arc4.UInt32(255), arc4.UInt32(128)
+        )
+
+        # Iterate over array
+        total = UInt64(0)
+        for uint32_item in static_uint32_array:
+            total += uint32_item.native
+
+        # Use type alias
+        aliased_static = AliasedStaticArray(arc4.UInt8(101))
+        aliased_static[0] = arc4.UInt8(202)
+```
+
+### Dynamic Arrays
+
+```python
+# Define dynamic array type alias
+goodbye: t.TypeAlias = arc4.DynamicArray[arc4.String]
+
+class Arc4DynamicArray(ARC4Contract):
+    @abimethod()
+    def hello(self, name: arc4.String) -> String:
+        # Create dynamic array
+        dynamic_string_array = arc4.DynamicArray[arc4.String](arc4.String("Hello "))
+
+        # Extend array
+        extension = arc4.DynamicArray[arc4.String](name, arc4.String("!"))
+        dynamic_string_array.extend(extension)
+
+        # Copy and modify
+        copied_array = dynamic_string_array.copy()
+        copied_array.pop()
+        copied_array.append(arc4.String("world!"))
+
+        # Iterate over array
+        greeting = String()
+        for x in dynamic_string_array:
+            greeting += x.native
+
+        return greeting
+```
+
+### Dynamic Bytes
+
+```python
+@abimethod()
+def arc4_dynamic_bytes(self) -> arc4.DynamicBytes:
+    # Create dynamic bytes
+    dynamic_bytes = arc4.DynamicBytes(b"\xff\xff\xff")
+
+    # Access native bytes
+    native_dynamic_bytes = dynamic_bytes.native
+
+    # Modify bytes
+    dynamic_bytes[0] = arc4.Byte(0)
+    dynamic_bytes.extend(arc4.DynamicBytes(b"\xaa\xbb\xcc"))
+    dynamic_bytes.pop()
+    dynamic_bytes.append(arc4.Byte(255))
+
+    return dynamic_bytes
+```
+
+## Structs and Tuples
+
+### Structs
+
+```python
+class Todo(arc4.Struct):
+    task: arc4.String
+    completed: arc4.Bool
+
+Todos: t.TypeAlias = arc4.DynamicArray[Todo]
+
+class Arc4Struct(ARC4Contract):
+    def __init__(self) -> None:
+        self.todos = Todos()
+
+    @abimethod()
+    def add_todo(self, task: arc4.String) -> Todos:
+        # Create and add struct instance
+        todo = Todo(task=task, completed=arc4.Bool(False))
+        
+        if not self.todos:
+            self.todos = Todos(todo.copy())
+        else:
+            self.todos.append(todo.copy())
+
+        return self.todos
+
+    @abimethod()
+    def complete_todo(self, task: arc4.String) -> None:
+        # Modify struct field
+        for index in urange(self.todos.length):
+            if self.todos[index].task == task:
+                self.todos[index].completed = arc4.Bool(True)
+                break
+```
+
+### Tuples
+
+```python
+# Define tuple type
+contact_info_tuple = arc4.Tuple[arc4.String, arc4.String, arc4.UInt64]
+
+class Arc4Tuple(ARC4Contract):
+    def __init__(self) -> None:
+        self.contact_info = GlobalState(
+            contact_info_tuple((
+                arc4.String(""), 
+                arc4.String(""), 
+                arc4.UInt64(0)
+            ))
+        )
+
+    @abimethod()
+    def add_contact_info(self, contact: contact_info_tuple) -> UInt64:
+        # Unpack tuple values
+        name, email, phone = contact.native
+        self.contact_info.value = contact
+        return phone.native
+
+    @abimethod()
+    def return_contact(self) -> arc4.Tuple[arc4.String, arc4.String, arc4.UInt64]:
+        # Return tuple
+        return self.contact_info.value
+```
+
+## Best Practices
+
+1. **Integer Operations**:
+   - Use `.native` for arithmetic operations
+   - Choose appropriate integer size
+   - Handle overflow conditions
+   - Convert back to ARC4 types for returns
+
+2. **Array Management**:
+   - Use static arrays for fixed-size collections
+   - Use dynamic arrays for variable-size collections
+   - Make copies when needed
+   - Handle array bounds properly
+
+3. **Struct Usage**:
+   - Define clear struct layouts
+   - Use appropriate field types
+   - Copy structs when storing
+   - Validate struct data
+
+4. **Type Safety**:
+   - Use type aliases for clarity
+   - Verify type conversions
+   - Handle type constraints
+   - Document type requirements
+
+5. **Memory Management**:
+   - Consider size limitations
+   - Use appropriate data structures
+   - Clean up unused data
+   - Optimize storage usage
+
+6. **Performance**:
+   - Choose efficient types
+   - Minimize type conversions
+   - Use appropriate data structures
+   - Consider operation costs
+
+This guide demonstrates the various ARC4 data types available in Algorand smart contracts using Python. Understanding these types is crucial for developing efficient and type-safe smart contracts.

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

@@ -0,0 +1,235 @@
+# Algorand Standard Assets (ASA) in Python
+
+This guide demonstrates how to work with Algorand Standard Assets (ASAs) using Python, including creation, management, transfer, and deletion operations.
+
+## Creating Assets
+
+### Creating a Fungible Token
+
+```python
+from algokit_utils import AssetCreateParams
+
+# Create fungible token with 10 million units
+txn_result = algorand_client.send.asset_create(
+    AssetCreateParams(
+        sender=account_a.address,
+        total=10_000_000,
+        decimals=6,
+        default_frozen=False,  # optional
+        manager=account_a.address,  # optional
+        reserve=account_a.address,  # optional
+        freeze=account_a.address,  # optional
+        clawback=account_a.address,  # optional
+        unit_name="MYA",
+        asset_name="My Asset",
+    )
+)
+```
+
+### Creating an NFT
+
+```python
+# Create a 1/1 NFT
+txn_result = algorand_client.send.asset_create(
+    AssetCreateParams(
+        sender=account_a.address,
+        total=1,
+        asset_name="My NFT",
+        unit_name="MNFT",
+        decimals=0,
+        url="metadata URL",
+        metadata_hash=b"Hash of the metadata URL",
+    )
+)
+```
+
+## Asset Transfers
+
+### Basic Transfer
+
+```python
+from algokit_utils import AssetTransferParams
+
+# Transfer 1 unit of asset
+txn_result = algorand_client.send.asset_transfer(
+    AssetTransferParams(
+        sender=account_a.address,
+        asset_id=1234,
+        receiver=account_b.address,
+        amount=1,
+    )
+)
+```
+
+## Asset Participation
+
+### Opt-In
+
+```python
+from algokit_utils import AssetOptInParams
+
+# Opt-in to an asset
+txn_result = algorand_client.send.asset_opt_in(
+    AssetOptInParams(
+        sender=account_a.address,
+        asset_id=1234,
+    )
+)
+```
+
+### Opt-Out
+
+```python
+from algokit_utils import AssetOptOutParams
+
+# Opt-out of an asset
+txn_result = algorand_client.send.asset_opt_out(
+    params=AssetOptOutParams(
+        sender=account_a.address,
+        asset_id=1234,
+        creator=account_b.address,
+    ),
+    ensure_zero_balance=True,  # Verify zero balance before opt-out
+)
+```
+
+## Asset Management
+
+### Freezing Assets
+
+```python
+from algokit_utils import AssetFreezeParams
+
+# Freeze assets
+txn_result = algorand_client.send.asset_freeze(
+    AssetFreezeParams(
+        sender=account_a.address,
+        asset_id=1234,
+        account=account_b.address,  # Account to freeze
+        frozen=True,
+    )
+)
+
+# Unfreeze assets
+txn_result = algorand_client.send.asset_freeze(
+    AssetFreezeParams(
+        sender=account_a.address,
+        asset_id=1234,
+        account=account_b.address,
+        frozen=False,
+    )
+)
+```
+
+### Clawback
+
+```python
+# Clawback assets from an account
+txn_result = algorand_client.send.asset_transfer(
+    AssetTransferParams(
+        sender=manager.address,
+        asset_id=1234,
+        amount=1,
+        receiver=manager.address,
+        clawback_target=account_to_be_clawbacked.address,
+    )
+)
+```
+
+### Updating Asset Configuration
+
+```python
+from algokit_utils import AssetConfigParams
+
+# Update asset configuration
+txn_result = algorand_client.send.asset_config(
+    AssetConfigParams(
+        sender=account_a.address,
+        asset_id=1234,
+        manager=account_b.address,
+        reserve=account_b.address,
+        freeze=account_b.address,
+        clawback=account_b.address,
+    )
+)
+```
+
+### Destroying Assets
+
+```python
+from algokit_utils import AssetDestroyParams
+
+# Destroy an asset
+txn_result = algorand_client.send.asset_destroy(
+    AssetDestroyParams(
+        sender=account_a.address,
+        asset_id=1234,
+    )
+)
+```
+
+## Best Practices
+
+1. **Asset Creation**:
+   - Choose appropriate decimals for fungible tokens
+   - Set meaningful unit names and asset names
+   - Consider immutability requirements
+   - Document metadata URLs and hashes
+
+2. **Asset Transfer**:
+   - Verify opt-in status before transfers
+   - Handle transfer failures gracefully
+   - Consider minimum balance requirements
+   - Track transfer status
+
+3. **Asset Management**:
+   - Carefully assign management roles
+   - Document role assignments
+   - Implement proper access controls
+   - Monitor asset operations
+
+4. **Freezing and Clawback**:
+   - Use freeze capability judiciously
+   - Document freeze/clawback policies
+   - Implement proper authorization
+   - Monitor frozen accounts
+
+5. **Configuration Updates**:
+   - Plan configuration changes carefully
+   - Document configuration history
+   - Verify manager authorization
+   - Test configuration changes
+
+6. **Asset Deletion**:
+   - Verify creator ownership
+   - Ensure zero circulation
+   - Document deletion reasons
+   - Handle deletion failures
+
+## Security Considerations
+
+1. **Access Control**:
+   - Verify transaction sender authorization
+   - Implement role-based controls
+   - Protect management keys
+   - Monitor suspicious activity
+
+2. **Asset Parameters**:
+   - Choose parameters carefully
+   - Consider immutability implications
+   - Document parameter decisions
+   - Test parameter effects
+
+3. **Operational Security**:
+   - Implement proper error handling
+   - Log important operations
+   - Monitor asset activities
+   - Regular security audits
+
+4. **User Protection**:
+   - Clear documentation
+   - Proper error messages
+   - User notifications
+   - Recovery procedures
+
+This guide demonstrates the various operations available for Algorand Standard Assets using Python. Understanding these operations is crucial for developing applications that work with ASAs effectively and securely.