@goplausible/openclaw-algorand-plugin 0.5.0

package/skills/algorand-python/references/implement-arc-standards-arc32-arc56.md

@@ -0,0 +1,101 @@
+# ARC-32/56 Client Usage (Python)
+
+This reference covers generating and using ARC-32/ARC-56 application specifications in Python.
+
+## Table of Contents
+
+- [Generating App Specs](#generating-app-specs)
+- [Python Client Usage](#python-client-usage)
+  - [Factory and Deployment](#factory-and-deployment)
+  - [Calling Methods](#calling-methods)
+  - [State Access](#state-access)
+- [Converting ARC-32 to ARC-56](#converting-arc-32-to-arc-56)
+- [Events (ARC-28)](#events-arc-28)
+
+## Generating App Specs
+
+```bash
+# Compile Python contract - generates both .arc32.json and .arc56.json
+puyapy contracts/my_contract.py
+
+# Or via AlgoKit
+algokit project run build
+```
+
+Output files:
+- `MyContract.arc32.json` - Legacy app spec
+- `MyContract.arc56.json` - Modern app spec
+
+### Generate Typed Clients
+
+```bash
+# Python client from ARC-56
+puyapy-clientgen MyContract.arc56.json
+
+# Or with AlgoKit CLI
+algokit generate client -o ./clients MyContract.arc56.json
+```
+
+## Python Client Usage
+
+### Factory and Deployment
+
+```python
+from algokit_utils import AlgorandClient
+from artifacts.calculator_client import CalculatorFactory
+
+algorand = AlgorandClient.default_localnet()
+
+# Deploy new contract
+factory = algorand.client.get_typed_app_factory(CalculatorFactory)
+app_client, _ = factory.deploy(
+    on_schema_break="replace",
+    on_update="update",
+)
+```
+
+### Calling Methods
+
+```python
+# Call methods with type hints
+result = app_client.send.add(a=10, b=20)
+print(result.return_value)  # int: 30
+```
+
+### State Access
+
+```python
+# Read state
+state = app_client.state.global_state.get_all()
+print(state["counter"])  # Typed value
+```
+
+## Converting ARC-32 to ARC-56
+
+AlgoKit Utils provides a conversion utility for migrating legacy ARC-32 specs:
+
+```python
+from algokit_utils.applications.app_spec import arc32_to_arc56
+
+arc56_spec = arc32_to_arc56(arc32_spec)
+```
+
+## Events (ARC-28)
+
+Events are emitted using `arc4.emit()` with typed event structs:
+
+```python
+from algopy import arc4
+
+class Transfer(arc4.Struct):
+    from_addr: arc4.Address
+    to_addr: arc4.Address
+    amount: arc4.UInt64
+
+# In contract method
+arc4.emit(Transfer(
+    from_addr=arc4.Address(sender),
+    to_addr=arc4.Address(receiver),
+    amount=arc4.UInt64(amount),
+))
+```

package/skills/algorand-python/references/implement-arc-standards-arc4.md

@@ -0,0 +1,154 @@
+# ARC-4 Implementation (Python)
+
+This reference covers implementing and calling ARC-4 methods in Algorand Python.
+
+## Table of Contents
+
+- [Using ARC-4 Types in Contracts](#using-arc-4-types-in-contracts)
+- [Calling ARC-4 Methods](#calling-arc-4-methods)
+  - [From Another Contract](#from-another-contract)
+  - [From Client (AlgoKit Utils)](#from-client-algokit-utils)
+- [Common ARC-4 Patterns](#common-arc-4-patterns)
+  - [Structs](#structs)
+  - [Arrays](#arrays)
+  - [Bare Methods](#bare-methods)
+
+## Using ARC-4 Types in Contracts
+
+```python
+from algopy import ARC4Contract, arc4, Account, Asset, Application
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def demo_types(
+        self,
+        # Primitive types
+        amount: arc4.UInt64,
+        flag: arc4.Bool,
+        name: arc4.String,
+
+        # Reference types (automatically handled)
+        user: Account,      # Passed as Account, encoded as uint8 index
+        token: Asset,       # Passed as Asset, encoded as uint8 index
+        app: Application,   # Passed as Application, encoded as uint8 index
+
+        # Complex types
+        data: arc4.DynamicBytes,
+        addr: arc4.Address,
+    ) -> arc4.String:
+        return arc4.String("Success")
+
+    @arc4.abimethod
+    def with_transaction(
+        self,
+        payment: gtxn.PaymentTransaction,  # Preceding payment in group
+        amount: arc4.UInt64,
+    ) -> None:
+        assert payment.receiver == Global.current_application_address
+```
+
+## Calling ARC-4 Methods
+
+### From Another Contract
+
+```python
+from algopy import arc4, Application
+
+# Call method on another contract using method reference
+result, txn = arc4.abi_call(
+    OtherContract.some_method,
+    arg1,
+    arg2,
+    app_id=other_app,
+)
+
+# Or using method signature string
+result, txn = arc4.abi_call[arc4.String](
+    "greet(string)string",
+    arc4.String("World"),
+    app_id=other_app,
+)
+```
+
+### From Client (AlgoKit Utils)
+
+```python
+result = client.send.add(a=10, b=20)
+
+# Access return value
+sum_value = result.return_value
+```
+
+### Getting Selector in Contract
+
+```python
+from algopy import arc4
+
+# Get selector for a method by signature string
+selector = arc4.arc4_signature("add(uint64,uint64)uint128")
+
+# Or from a contract method reference
+selector = arc4.arc4_signature(Calculator.add)
+```
+
+## Common ARC-4 Patterns
+
+### Structs
+
+```python
+from algopy import ARC4Contract, arc4
+
+class UserInfo(arc4.Struct):
+    name: arc4.String
+    balance: arc4.UInt64
+    active: arc4.Bool
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def get_user(self, addr: arc4.Address) -> UserInfo:
+        return UserInfo(
+            name=arc4.String("Alice"),
+            balance=arc4.UInt64(1000),
+            active=arc4.Bool(True),
+        )
+```
+
+### Arrays
+
+```python
+from algopy import ARC4Contract, arc4
+from typing import Literal
+
+# Fixed-size array
+Balances = arc4.StaticArray[arc4.UInt64, Literal[10]]
+
+# Dynamic array
+Names = arc4.DynamicArray[arc4.String]
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def process_list(self, items: arc4.DynamicArray[arc4.UInt64]) -> arc4.UInt64:
+        total = arc4.UInt64(0)
+        for item in items:
+            total = arc4.UInt64(total.native + item.native)
+        return total
+```
+
+### Bare Methods
+
+```python
+from algopy import ARC4Contract, arc4
+
+class MyContract(ARC4Contract):
+    @arc4.baremethod(create="require")
+    def create(self) -> None:
+        """Called on app creation with no args."""
+        pass
+
+    @arc4.baremethod(allow_actions=["OptIn"])
+    def opt_in(self) -> None:
+        """Called on OptIn with no args."""
+        pass
+```
+
+Bare calls are identified by `NumAppArgs == 0`.

package/skills/algorand-python/references/implement-arc-standards.md

@@ -0,0 +1,39 @@
+# Implement ARC Standards (Python)
+
+This reference covers implementing ARC standards in Algorand Python smart contracts and clients. ARC-4 defines the ABI for method calls and type encoding, while ARC-56 provides the modern application specification format for typed client generation.
+
+## ARC-4 Contract Method Example
+
+```python
+from algopy import ARC4Contract, arc4
+
+class Calculator(ARC4Contract):
+    @arc4.abimethod
+    def add(self, a: arc4.UInt64, b: arc4.UInt64) -> arc4.UInt128:
+        return arc4.UInt128(a.native + b.native)
+```
+
+## Using Typed Clients with ARC-56
+
+```python
+from algokit_utils import AlgorandClient
+from artifacts.calculator_client import CalculatorFactory
+
+algorand = AlgorandClient.default_localnet()
+
+# Deploy new contract
+factory = algorand.client.get_typed_app_factory(CalculatorFactory)
+app_client, _ = factory.deploy(
+    on_schema_break="replace",
+    on_update="update",
+)
+
+# Call methods with type hints
+result = app_client.send.add(a=10, b=20)
+print(result.return_value)  # int: 30
+```
+
+## References
+
+- [Python ARC-4 Implementation](./implement-arc-standards-arc4.md) - ARC-4 types, contracts, and client calls
+- [Python ARC-32/56 Client Usage](./implement-arc-standards-arc32-arc56.md) - App specs, typed clients, and state access

package/skills/algorand-python/references/troubleshoot-errors-contract.md

@@ -0,0 +1,355 @@
+# Smart Contract Errors (Python)
+
+Python-focused fixes for common Algorand smart contract errors.
+
+## Table of Contents
+
+- [Logic Eval Errors](#logic-eval-errors)
+  - [Assert Failed](#assert-failed)
+  - [Opcode Budget Exceeded](#opcode-budget-exceeded)
+  - [Invalid Program](#invalid-program)
+  - [Stack Underflow](#stack-underflow)
+  - [Byte/Int Type Mismatch](#byteint-type-mismatch)
+- [ABI Errors](#abi-errors)
+  - [Method Not Found](#method-not-found)
+  - [ABI Encoding Error](#abi-encoding-error)
+  - [Return Value Decoding Error](#return-value-decoding-error)
+- [State Errors](#state-errors)
+  - [Global State Full](#global-state-full)
+  - [Local State Not Opted In](#local-state-not-opted-in)
+  - [Box Not Found](#box-not-found)
+  - [Box MBR Not Met](#box-mbr-not-met)
+- [Inner Transaction Errors](#inner-transaction-errors)
+- [Debugging Tips](#debugging-tips)
+
+## Logic Eval Errors
+
+### Assert Failed
+
+```
+logic eval error: assert failed pc=123
+```
+
+**Cause:** An `assert` statement evaluated to false.
+
+**Debug with source maps (LogicError):**
+
+```python
+from algokit_utils import LogicError
+
+try:
+    app_client.send.my_method(value=0)
+except LogicError as e:
+    print(e)       # Shows: assert failed at contracts/my_contract.py:45
+    print(e.pc)    # Program counter: 123
+    print(e.line)  # Source line number
+```
+
+**Common causes:**
+- Input validation failed (e.g., `assert amount > 0`)
+- Authorization check failed (e.g., `assert Txn.sender == self.owner`)
+- State precondition not met (e.g., `assert self.is_initialized`)
+
+**Fix:** Check the assertion condition and ensure inputs satisfy it.
+
+### Opcode Budget Exceeded
+
+```
+logic eval error: dynamic cost budget exceeded
+```
+
+**Cause:** Contract exceeded the 700 opcode budget per app call.
+
+**Budget limits:**
+| Context | Budget |
+|---------|--------|
+| Single app call | 700 opcodes |
+| Max pooled (16 app calls) | 11,200 opcodes |
+| Logic signature | 20,000 opcodes |
+
+**Fix - Pool budget with extra app calls:**
+```python
+# Add dummy app calls to increase budget
+algorand.new_group()
+    .add_app_call_method_call(actual_call_params)
+    .add_app_call(AppCallParams(
+        sender=sender,
+        app_id=app_id,
+        on_complete=OnComplete.NoOp,
+        args=[b"noop"]  # Dummy call for budget
+    ))
+    .send()
+```
+
+**Optimize expensive operations:**
+```python
+# EXPENSIVE - iteration over large data
+for i in range(100):
+    process(data[i])
+
+# CHEAPER - batch operations or use Box storage
+box_data = Box(Bytes, key=b"data")
+```
+
+**Split across multiple calls:**
+```python
+# Instead of one large operation, split into phases
+@arc4.abimethod
+def process_phase1(self) -> None: ...
+
+@arc4.abimethod
+def process_phase2(self) -> None: ...
+```
+
+### Invalid Program
+
+```
+logic eval error: invalid program
+```
+
+**Cause:** The TEAL program is malformed or uses unsupported opcodes.
+
+**Common causes:**
+- Compiling for wrong AVM version
+- Using opcodes not supported on target network
+- Corrupted approval/clear program bytes
+
+**Fix:** Ensure compilation targets the correct AVM version.
+
+### Stack Underflow
+
+```
+logic eval error: stack underflow
+```
+
+**Cause:** Operation tried to pop from empty stack.
+
+**In Algorand Python:** This usually indicates a bug in low-level operations. Check any `op.*` calls.
+
+### Byte/Int Type Mismatch
+
+```
+logic eval error: assert failed: wanted type uint64 but got []byte
+```
+
+**Cause:** Wrong type passed to an operation.
+
+**Common in Algorand Python:**
+```python
+# INCORRECT - String where UInt64 expected
+assert payment.amount == "1000000"
+
+# CORRECT - Use proper types
+assert payment.amount == UInt64(1_000_000)
+```
+
+## ABI Errors
+
+### Method Not Found
+
+```
+error: method "foo(uint64)void" not found
+```
+
+**Cause:** Calling a method that doesn't exist in the contract ABI.
+
+**Fix:**
+1. Regenerate the typed client after contract changes
+2. Check the method signature matches exactly
+3. Verify the contract was deployed with the latest code
+
+### ABI Encoding Error
+
+```
+ABIEncodingError: value out of range for uint64
+```
+
+**Cause:** Value doesn't fit the ABI type.
+
+**Examples:**
+```python
+# INCORRECT - Negative value for uint64
+arc4.UInt64(-1)
+
+# INCORRECT - Value too large
+arc4.UInt8(256)  # Max is 255
+
+# CORRECT - Use appropriate type
+arc4.UInt64(0)
+arc4.UInt16(256)
+```
+
+### Return Value Decoding Error
+
+```
+error: could not decode return value
+```
+
+**Cause:** Method returned unexpected data format.
+
+**Common causes:**
+- Contract didn't log the return value properly
+- Wrong return type in client
+- Transaction failed before return
+
+**Fix:** Check contract method has correct return annotation.
+
+## State Errors
+
+### Global State Full
+
+```
+logic eval error: store global state: failed
+```
+
+**Cause:** Exceeded declared global state schema.
+
+**Fix:** Increase schema in contract deployment:
+```python
+class MyContract(ARC4Contract):
+    # Declare more state slots in schema
+    @arc4.abimethod(create=True)
+    def create(self) -> None:
+        pass
+```
+
+### Local State Not Opted In
+
+```
+logic eval error: application APPID not opted in
+```
+
+**Cause:** Account hasn't opted into the application.
+
+**Fix:** Opt in before accessing local state:
+```python
+algorand.send.app_call(AppCallParams(
+    sender=user_address,
+    app_id=app_id,
+    on_complete=OnComplete.OptIn,
+))
+```
+
+### Box Not Found
+
+```
+logic eval error: box not found
+```
+
+**Cause:** Accessing a box that doesn't exist.
+
+**Fix:** Create box before access or check existence:
+```python
+# In contract - check if box exists
+if self.my_box.exists:
+    value = self.my_box.value
+else:
+    self.my_box.value = default_value
+```
+
+### Box MBR Not Met
+
+```
+logic eval error: box create with insufficient funds
+```
+
+**Cause:** App account lacks funds for box minimum balance requirement.
+
+**MBR formula:** `2500 + (400 * (key_length + value_length))` microAlgos per box
+
+**Fix:** Fund the app account:
+```python
+algorand.send.payment(PaymentParams(
+    sender=funder.address,
+    receiver=app_client.app_address,
+    amount=AlgoAmount(algo=1),  # Cover box MBR
+))
+```
+
+## Inner Transaction Errors
+
+### Insufficient Balance for Inner Txn
+
+```
+logic eval error: insufficient balance
+```
+
+**Cause:** App account lacks funds for inner transaction amount.
+
+**Fix:** Fund the app account before inner transactions:
+```python
+# Fund app before calling method with inner transactions
+algorand.send.payment(PaymentParams(
+    sender=deployer.address,
+    receiver=app_client.app_address,
+    amount=AlgoAmount(algo=5),
+))
+```
+
+### Inner Transaction Limit
+
+```
+logic eval error: too many inner transactions
+```
+
+**Cause:** Exceeded 256 inner transactions per group.
+
+**Fix:** Split operations across multiple outer transactions.
+
+### App Not Opted Into Asset
+
+```
+logic eval error: asset ASSET_ID not opted in
+```
+
+**Cause:** Contract account isn't opted into the asset.
+
+**Fix:** Add opt-in method to contract:
+```python
+@arc4.abimethod
+def opt_in_to_asset(self, asset: Asset) -> None:
+    itxn.AssetTransfer(
+        xfer_asset=asset,
+        asset_receiver=Global.current_application_address,
+        asset_amount=0,
+        fee=0
+    ).submit()
+```
+
+## Debugging Tips
+
+### Enable Debug Logging
+
+```python
+import logging
+logging.getLogger("algokit").setLevel(logging.DEBUG)
+```
+
+### Catch LogicError with Source Map
+
+```python
+from algokit_utils import LogicError
+
+try:
+    app_client.send.my_method(value=0)
+except LogicError as e:
+    print(e)       # Full error with source mapping
+    print(e.pc)    # Program counter
+    print(e.line)  # Source line number
+```
+
+### Check Program Counter Location
+
+When you see `pc=123`, use algokit to find the source:
+
+```bash
+algokit compile contracts/my_contract.py --output-sourcemap
+```
+
+Then map the PC to source using the generated `.map` file.
+
+## References
+
+- [Debugging Smart Contracts](https://dev.algorand.co/concepts/smart-contracts/debugging/)
+- [AVM Opcodes Reference](https://dev.algorand.co/reference/teal/opcodes/)
+- [Error Handling in AlgoKit](https://dev.algorand.co/algokit/utils/typescript/debugging/)