openclaw-algorand-plugin 0.5.0

package/skills/algorand-python/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: algorand-python
+description: Comprehensive guide for Algorand Python (PuyaPy) smart contract development — contract building with decorators, storage, transactions, types, AlgoKit Utils, ARC standards, and troubleshooting. This is the parent skill for all Python-specific Algorand content. Use when writing Python contract code, working with algopy decorators, understanding Algorand Python storage patterns, using AlgoKit Utils in Python, or troubleshooting Python-specific errors. Strong triggers include "Algorand Python", "PuyaPy", "algopy", "ARC4Contract", "@arc4.abimethod", "GlobalState Python", "BoxMap Python", "algokit_utils Python", "pip install algokit-utils", "Python contract", "Python smart contract".
+---
+
+# Algorand Python
+
+This is the aggregated parent skill for all Python-specific Algorand development. Use the reference files below to find detailed guidance for each topic.
+
+## Quick Start
+
+```bash
+# Create Python project
+algokit init -n my-project -t python --answer preset_name production --defaults
+
+# Install AlgoKit Utils
+pip install algokit-utils
+
+# Development cycle
+algokit project run build    # Compile Python contracts
+algokit project run test     # Run tests
+```
+
+### Key Python Pattern
+
+```python
+from algopy import ARC4Contract, arc4
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def hello(self, name: arc4.String) -> arc4.String:
+        return arc4.String("Hello, " + name.native)
+```
+
+## Reference Guide
+
+Navigate to the appropriate reference based on your task. Each topic has one or more files.
+
+### Creating Python Projects
+
+Initialize Python AlgoKit projects with proper templates and presets.
+
+- [create-project.md](./references/create-project.md) — Python project creation
+- [create-project-reference.md](./references/create-project-reference.md) — Python presets and templates
+
+### Building Smart Contracts (Python)
+
+Python-specific contract building with PuyaPy, including deep-dive references for decorators, storage, transactions, and types.
+
+- [build-smart-contracts.md](./references/build-smart-contracts.md) — Python contract building guide
+- [build-smart-contracts-reference.md](./references/build-smart-contracts-reference.md) — Python repos and patterns
+- [build-smart-contracts-decorators.md](./references/build-smart-contracts-decorators.md) — `@arc4.abimethod`, `@arc4.baremethod`, `@subroutine`
+- [build-smart-contracts-storage.md](./references/build-smart-contracts-storage.md) — GlobalState, LocalState, Box, BoxMap, BoxRef
+- [build-smart-contracts-transactions.md](./references/build-smart-contracts-transactions.md) — Inner transactions, group transactions, fee pooling
+- [build-smart-contracts-types.md](./references/build-smart-contracts-types.md) — AVM types, ARC-4 types, reference types
+
+### AlgoKit Utils (Python)
+
+Interact with Algorand from Python applications.
+
+- [use-algokit-utils.md](./references/use-algokit-utils.md) — Python AlgoKit Utils overview
+- [use-algokit-utils-reference.md](./references/use-algokit-utils-reference.md) — AlgorandClient Python API reference
+
+### Implementing ARC Standards (Python)
+
+Python implementations of ARC-4, ARC-32, and ARC-56.
+
+- [implement-arc-standards.md](./references/implement-arc-standards.md) — Python ARC overview
+- [implement-arc-standards-arc4.md](./references/implement-arc-standards-arc4.md) — Python ARC-4 implementations
+- [implement-arc-standards-arc32-arc56.md](./references/implement-arc-standards-arc32-arc56.md) — Python typed client usage
+
+### Troubleshooting Errors (Python)
+
+Python-specific error diagnosis and fixes.
+
+- [troubleshoot-errors.md](./references/troubleshoot-errors.md) — Python error overview
+- [troubleshoot-errors-contract.md](./references/troubleshoot-errors-contract.md) — Contract errors with Python fixes
+- [troubleshoot-errors-transaction.md](./references/troubleshoot-errors-transaction.md) — Transaction errors with Python fixes
+
+## Topic Quick Reference
+
+| Topic | Files | Description |
+| ----- | ----- | ----------- |
+| Create Project | 2 | Python template initialization |
+| Build Contracts | 6 | PuyaPy contracts, decorators, storage, transactions, types |
+| AlgoKit Utils | 2 | AlgorandClient Python API |
+| ARC Standards | 3 | Python ARC implementations |
+| Troubleshoot | 3 | Python error fixes |
+
+## How to Use This Skill
+
+1. **Start here** to understand which reference you need
+2. **Read the topic `.md`** file for step-by-step guidance
+3. **Consult detail files** for specific subtopics (decorators, storage, types, etc.)
+4. **For language-agnostic content** (CLI, ARC specs, general workflows), see the `algorand-development` parent skill

package/skills/algorand-python/references/build-smart-contracts-decorators.md

@@ -0,0 +1,413 @@
+# Algorand Python Decorators
+
+Define smart contract methods and their behavior using decorators in Algorand Python.
+
+## When to use this reference
+
+Use this reference when:
+
+- Creating ABI methods that external callers can invoke
+- Defining bare methods for application lifecycle operations
+- Writing internal subroutines for code reuse
+- Controlling method visibility and call permissions
+- Handling application create, update, delete, and opt-in actions
+
+## Contract Base Classes
+
+### ARC4Contract (Recommended)
+
+Use `ARC4Contract` for contracts that expose ABI methods.
+
+```python
+from algopy import ARC4Contract, arc4
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def hello(self, name: arc4.String) -> arc4.String:
+        return "Hello, " + name
+```
+
+### Contract (Low-Level)
+
+Use `Contract` for raw approval/clear program control.
+
+```python
+from algopy import Contract, UInt64
+
+class MyContract(Contract):
+    def approval_program(self) -> UInt64:
+        return UInt64(1)  # Approve
+
+    def clear_state_program(self) -> UInt64:
+        return UInt64(1)  # Approve
+```
+
+## @arc4.abimethod
+
+Marks a method as an ABI method callable by external transactions.
+
+### Basic Usage
+
+```python
+from algopy import ARC4Contract, arc4, UInt64
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def add(self, a: arc4.UInt64, b: arc4.UInt64) -> arc4.UInt64:
+        return arc4.UInt64(a.native + b.native)
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `name` | `str` | Method name | Override method name in ABI |
+| `create` | `"allow"`, `"require"`, `"disallow"` | `"disallow"` | Application creation behavior |
+| `allow_actions` | `list[str]` | `["NoOp"]` | Allowed OnComplete actions |
+| `readonly` | `bool` | `False` | Mark as read-only (no state changes) |
+| `default_args` | `dict` | `{}` | Default argument sources |
+
+### Application Creation
+
+```python
+from algopy import ARC4Contract, arc4, String
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        self.name = String()
+
+    # CORRECT - Method that creates the application
+    @arc4.abimethod(create="require")
+    def create(self, name: arc4.String) -> None:
+        self.name = name.native
+
+    # CORRECT - Method that can optionally create
+    @arc4.abimethod(create="allow")
+    def initialize(self, name: arc4.String) -> None:
+        self.name = name.native
+
+    # CORRECT - Method that cannot create (default)
+    @arc4.abimethod  # create="disallow" is default
+    def update_name(self, name: arc4.String) -> None:
+        self.name = name.native
+```
+
+### OnComplete Actions
+
+```python
+from algopy import ARC4Contract, arc4, Txn
+
+class MyContract(ARC4Contract):
+    # CORRECT - Allow opt-in calls
+    @arc4.abimethod(allow_actions=["OptIn"])
+    def opt_in(self) -> None:
+        pass
+
+    # CORRECT - Allow close-out calls
+    @arc4.abimethod(allow_actions=["CloseOut"])
+    def close_out(self) -> None:
+        pass
+
+    # CORRECT - Allow update calls (requires UpdateApplication)
+    @arc4.abimethod(allow_actions=["UpdateApplication"])
+    def update(self) -> None:
+        assert Txn.sender == self.creator
+
+    # CORRECT - Allow delete calls
+    @arc4.abimethod(allow_actions=["DeleteApplication"])
+    def delete(self) -> None:
+        assert Txn.sender == self.creator
+
+    # CORRECT - Allow multiple actions
+    @arc4.abimethod(allow_actions=["NoOp", "OptIn"])
+    def register(self) -> None:
+        pass
+```
+
+### Read-Only Methods
+
+```python
+from algopy import ARC4Contract, arc4, UInt64
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        self.counter = UInt64(0)
+
+    # CORRECT - Mark as read-only for simulation
+    @arc4.abimethod(readonly=True)
+    def get_counter(self) -> arc4.UInt64:
+        return arc4.UInt64(self.counter)
+```
+
+### Custom Method Names
+
+```python
+from algopy import ARC4Contract, arc4
+
+class MyContract(ARC4Contract):
+    # CORRECT - Override ABI method name
+    @arc4.abimethod(name="getBalance")
+    def get_balance(self) -> arc4.UInt64:
+        return arc4.UInt64(0)
+```
+
+### Default Arguments
+
+```python
+from algopy import ARC4Contract, arc4, Asset, Global
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        self.asset = Asset()
+
+    # CORRECT - Default arg from state or constant
+    @arc4.abimethod(
+        default_args={
+            "asset": "asset",  # From self.asset
+            "sender": "global.creator_address"  # From Global
+        }
+    )
+    def transfer(self, asset: Asset, sender: arc4.Address) -> None:
+        pass
+```
+
+## @arc4.baremethod
+
+Marks a method as a bare method (no ABI selector, no arguments/return).
+
+### Basic Usage
+
+```python
+from algopy import ARC4Contract, arc4
+
+class MyContract(ARC4Contract):
+    # CORRECT - Bare method for creation
+    @arc4.baremethod(create="require")
+    def create(self) -> None:
+        pass
+
+    # CORRECT - Bare method for opt-in
+    @arc4.baremethod(allow_actions=["OptIn"])
+    def opt_in(self) -> None:
+        pass
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `create` | `"allow"`, `"require"`, `"disallow"` | `"disallow"` | Application creation behavior |
+| `allow_actions` | `list[str]` | `["NoOp"]` | Allowed OnComplete actions |
+
+### Common Bare Method Patterns
+
+```python
+from algopy import ARC4Contract, arc4, Txn
+
+class MyContract(ARC4Contract):
+    # CORRECT - Bare create (no arguments needed)
+    @arc4.baremethod(create="require")
+    def create(self) -> None:
+        pass
+
+    # CORRECT - Bare update
+    @arc4.baremethod(allow_actions=["UpdateApplication"])
+    def update(self) -> None:
+        assert Txn.sender == self.creator
+
+    # CORRECT - Bare delete
+    @arc4.baremethod(allow_actions=["DeleteApplication"])
+    def delete(self) -> None:
+        assert Txn.sender == self.creator
+
+    # CORRECT - Bare opt-in
+    @arc4.baremethod(allow_actions=["OptIn"])
+    def opt_in(self) -> None:
+        pass
+
+    # CORRECT - Bare close-out
+    @arc4.baremethod(allow_actions=["CloseOut"])
+    def close_out(self) -> None:
+        pass
+```
+
+## @subroutine
+
+Marks a function as a reusable subroutine (internal, not callable externally).
+
+### Basic Usage
+
+```python
+from algopy import ARC4Contract, arc4, UInt64, subroutine
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def calculate(self, value: arc4.UInt64) -> arc4.UInt64:
+        result = self._double(value.native)
+        return arc4.UInt64(result)
+
+    # CORRECT - Private subroutine
+    @subroutine
+    def _double(self, value: UInt64) -> UInt64:
+        return value * UInt64(2)
+```
+
+### Module-Level Subroutines
+
+```python
+from algopy import ARC4Contract, arc4, UInt64, subroutine
+
+# CORRECT - Module-level subroutine
+@subroutine
+def calculate_fee(amount: UInt64) -> UInt64:
+    return amount * UInt64(3) // UInt64(100)
+
+class MyContract(ARC4Contract):
+    @arc4.abimethod
+    def process(self, amount: arc4.UInt64) -> arc4.UInt64:
+        fee = calculate_fee(amount.native)
+        return arc4.UInt64(fee)
+```
+
+### Inline Parameter
+
+Control whether the subroutine is inlined at call sites.
+
+```python
+from algopy import subroutine, UInt64
+
+# CORRECT - Force inlining (small, frequently called)
+@subroutine(inline=True)
+def is_valid(value: UInt64) -> bool:
+    return value > UInt64(0)
+
+# CORRECT - Prevent inlining (large, called multiple times)
+@subroutine(inline=False)
+def complex_calculation(a: UInt64, b: UInt64, c: UInt64) -> UInt64:
+    # Complex logic here
+    return a * b + c
+
+# CORRECT - Let compiler decide (default)
+@subroutine  # inline="auto" is default
+def helper(value: UInt64) -> UInt64:
+    return value + UInt64(1)
+```
+
+## Lifecycle Methods
+
+### __init__ (State Initialization)
+
+```python
+from algopy import ARC4Contract, UInt64, String
+
+class MyContract(ARC4Contract):
+    def __init__(self) -> None:
+        # Initialize state - runs on application creation
+        self.counter = UInt64(0)
+        self.name = String("default")
+```
+
+### clear_state_program (Clear State)
+
+```python
+from algopy import ARC4Contract, UInt64
+
+class MyContract(ARC4Contract):
+    # CORRECT - Custom clear state logic
+    def clear_state_program(self) -> UInt64:
+        # Return 1 to approve, 0 to reject
+        return UInt64(1)
+```
+
+## Method Visibility Summary
+
+| Decorator | Externally Callable | Has ABI Selector | Can Have Args/Return |
+|-----------|---------------------|------------------|----------------------|
+| `@arc4.abimethod` | Yes | Yes | Yes |
+| `@arc4.baremethod` | Yes | No | No |
+| `@subroutine` | No | No | Yes |
+| (no decorator) | No | No | Yes (internal only) |
+
+## Common Mistakes
+
+### Using abimethod for Internal Logic
+
+```python
+# INCORRECT - Internal logic exposed as ABI method
+@arc4.abimethod
+def _calculate_fee(self, amount: arc4.UInt64) -> arc4.UInt64:
+    return arc4.UInt64(amount.native * UInt64(3) // UInt64(100))
+
+# CORRECT - Use subroutine for internal logic
+@subroutine
+def _calculate_fee(self, amount: UInt64) -> UInt64:
+    return amount * UInt64(3) // UInt64(100)
+```
+
+### Forgetting create Parameter for Creation Methods
+
+```python
+# INCORRECT - Cannot call this during creation
+@arc4.abimethod
+def create_app(self, name: arc4.String) -> None:
+    self.name = name.native
+
+# CORRECT - Explicitly allow or require creation
+@arc4.abimethod(create="require")
+def create_app(self, name: arc4.String) -> None:
+    self.name = name.native
+```
+
+### Arguments on Bare Methods
+
+```python
+# INCORRECT - Bare methods cannot have arguments
+@arc4.baremethod
+def opt_in(self, user_name: arc4.String) -> None:  # Error!
+    pass
+
+# CORRECT - Use abimethod if you need arguments
+@arc4.abimethod(allow_actions=["OptIn"])
+def opt_in(self, user_name: arc4.String) -> None:
+    pass
+
+# CORRECT - Bare method without arguments
+@arc4.baremethod(allow_actions=["OptIn"])
+def opt_in(self) -> None:
+    pass
+```
+
+### Missing Return Type on Subroutines
+
+```python
+# INCORRECT - Missing return type annotation
+@subroutine
+def calculate(value: UInt64):
+    return value * UInt64(2)
+
+# CORRECT - Include return type
+@subroutine
+def calculate(value: UInt64) -> UInt64:
+    return value * UInt64(2)
+```
+
+### Using Native Types in ABI Method Signatures
+
+```python
+# INCORRECT - ABI methods should use arc4 types for args/return
+@arc4.abimethod
+def add(self, a: UInt64, b: UInt64) -> UInt64:
+    return a + b
+
+# CORRECT - Use arc4 types in signature
+@arc4.abimethod
+def add(self, a: arc4.UInt64, b: arc4.UInt64) -> arc4.UInt64:
+    return arc4.UInt64(a.native + b.native)
+```
+
+## References
+
+- [Algorand Python Contract Structure](https://dev.algorand.co/algokit/languages/python/lg-contract-structure/)
+- [ARC-4 ABI Methods](https://dev.algorand.co/algokit/languages/python/lg-arc4/)
+- [algopy API Reference](https://dev.algorand.co/reference/algorand-python/api/api-algopy/)
+- [algopy.arc4 Reference](https://dev.algorand.co/reference/algorand-python/api/api-algopy-arc4/)

package/skills/algorand-python/references/build-smart-contracts-reference.md

@@ -0,0 +1,55 @@
+# Python Smart Contract Repository and Pattern Reference
+
+Python-specific repositories, paths, and patterns for building Algorand smart contracts with PuyaPy.
+
+## Priority Repositories
+
+### Priority 1: DevPortal Code Examples (Python)
+**Repository:** `algorandfoundation/devportal-code-examples`
+**Path:** `projects/python-examples/contracts/`
+
+Common contract patterns available:
+- State management examples (GlobalState, LocalState)
+- ARC-4 method examples
+- Inner transaction patterns
+- Box storage patterns
+
+Always retrieve corresponding test files alongside contracts.
+
+### Priority 2: Puya Compiler Examples
+**Repository:** `algorandfoundation/puya`
+**Path:** `examples/`
+
+Key examples:
+- `hello_world_arc4/` -- Basic ARC-4 contract structure
+- `voting/` -- State management, BoxMap patterns, complex logic
+- `amm/` -- Advanced patterns (multi-asset, inner transactions, BoxMap)
+- Search for `itxn` patterns for inner transaction examples
+
+### Priority 3: AlgoKit Python Template
+**Repository:** `algorandfoundation/algokit-python-template`
+
+Provides:
+- Project structure and scaffolding
+- Build and test configuration
+- Integration test patterns with generated clients
+
+## Pattern-Specific Lookups
+
+| Pattern | Where to Look |
+|---------|--------------|
+| Box storage / BoxMap | `puya/examples/voting/`, `puya/examples/amm/` |
+| Inner transactions | `puya/examples/` (search for itxn usage) |
+| ARC-4 methods | `puya/examples/hello_world_arc4/` |
+| State management | `devportal-code-examples/projects/python-examples/contracts/` |
+| AMM / DeFi | `puya/examples/amm/` |
+| Voting | `puya/examples/voting/` |
+| Decorators | See [build-smart-contracts-decorators.md](./build-smart-contracts-decorators.md) |
+| Storage types | See [build-smart-contracts-storage.md](./build-smart-contracts-storage.md) |
+| Transactions | See [build-smart-contracts-transactions.md](./build-smart-contracts-transactions.md) |
+| Types | See [build-smart-contracts-types.md](./build-smart-contracts-types.md) |
+
+## Supporting Repositories
+
+- `algorandfoundation/algokit-cli` -- CLI tool reference
+- `algorandfoundation/algokit-utils-ts` -- Utility functions for deployment and testing