openclaw-algorand-plugin 0.5.0

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

@@ -0,0 +1,265 @@
+# ARC-4: Application Binary Interface
+
+ARC-4 defines how to encode method calls, arguments, and return values for Algorand smart contracts. It enables interoperability between contracts, clients, wallets, and explorers.
+
+## Table of Contents
+
+- [ARC-4 Types](#arc-4-types)
+  - [Primitive Types](#primitive-types)
+  - [Complex Types](#complex-types)
+  - [Reference Types](#reference-types-arguments-only)
+  - [Transaction Types](#transaction-types-arguments-only)
+- [Using ARC-4 Types](#using-arc-4-types)
+- [Method Signatures and Selectors](#method-signatures-and-selectors)
+- [Encoding Rules](#encoding-rules)
+  - [Static vs Dynamic Types](#static-vs-dynamic-types)
+  - [Tuple Encoding](#tuple-encoding-head--tail)
+  - [Boolean Packing](#boolean-packing)
+- [Method Invocation](#method-invocation)
+- [Common Mistakes](#common-mistakes)
+
+## ARC-4 Types
+
+### Primitive Types
+
+| Type | Description | Encoding |
+|------|-------------|----------|
+| `uint<N>` | N-bit unsigned integer (8-512, N%8=0) | Big-endian N bits |
+| `byte` | Alias for `uint8` | 1 byte |
+| `bool` | Boolean (0 or 1) | MSB of 1 byte; consecutive bools are packed |
+| `ufixed<N>x<M>` | Fixed-point decimal | N bits, value = encoded / 10^M |
+
+### Complex Types
+
+| Type | Description | Encoding |
+|------|-------------|----------|
+| `address` | 32-byte Algorand address | Equivalent to `byte[32]` |
+| `string` | UTF-8 encoded text | 2-byte length prefix + bytes |
+| `<type>[N]` | Fixed-length array | N elements packed together |
+| `<type>[]` | Variable-length array | 2-byte length prefix + elements |
+| `(T1,T2,...,TN)` | Tuple | Head (offsets) + Tail (dynamic data) |
+
+### Reference Types (Arguments Only)
+
+| Type | Description | Encoded As |
+|------|-------------|------------|
+| `account` | Algorand account | `uint8` index into Accounts array |
+| `asset` | Algorand Standard Asset | `uint8` index into Foreign Assets array |
+| `application` | Algorand Application | `uint8` index into Foreign Apps array |
+
+**Important:** Reference types cannot be used as return types.
+
+### Transaction Types (Arguments Only)
+
+| Type | Description |
+|------|-------------|
+| `txn` | Any transaction |
+| `pay` | Payment transaction |
+| `axfer` | Asset transfer transaction |
+| `acfg` | Asset config transaction |
+| `afrz` | Asset freeze transaction |
+| `appl` | Application call transaction |
+| `keyreg` | Key registration transaction |
+
+Transaction arguments are encoded as preceding transactions in the group, not in ApplicationArgs.
+
+## Using ARC-4 Types
+
+### Python (Algorand Python)
+
+```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
+```
+
+### TypeScript (Algorand TypeScript)
+
+```typescript
+import { Contract, Account, Asset, Application, Global } from '@algorandfoundation/algorand-typescript'
+import { abimethod, UInt64, Bool, Str, DynamicBytes, Address } from '@algorandfoundation/algorand-typescript/arc4'
+import { PaymentTxn } from '@algorandfoundation/algorand-typescript/gtxn'
+
+class MyContract extends Contract {
+  @abimethod()
+  demoTypes(
+    // Primitive types
+    amount: UInt64,
+    flag: Bool,
+    name: Str,
+
+    // Reference types
+    user: Account,
+    token: Asset,
+    app: Application,
+
+    // Complex types
+    data: DynamicBytes,
+    addr: Address,
+  ): Str {
+    return new Str('Success')
+  }
+
+  @abimethod()
+  withTransaction(
+    payment: PaymentTxn,  // Preceding payment in group
+    amount: UInt64,
+  ): void {
+    assert(payment.receiver === Global.currentApplicationAddress)
+  }
+}
+```
+
+## Method Signatures and Selectors
+
+### Signature Format
+
+```
+method_name(arg1_type,arg2_type,...)return_type
+```
+
+- No spaces
+- No argument names
+- `void` for no return value
+
+### Examples
+
+| Method | Signature |
+|--------|-----------|
+| `def add(a: UInt64, b: UInt64) -> UInt128` | `add(uint64,uint64)uint128` |
+| `def greet(name: String) -> String` | `greet(string)string` |
+| `def transfer(to: Account, amt: UInt64) -> None` | `transfer(account,uint64)void` |
+| `def process(p: PaymentTxn, d: Bytes) -> None` | `process(pay,byte[])void` |
+
+### Selector Calculation
+
+```python
+import hashlib
+
+def get_selector(signature: str) -> bytes:
+    """Calculate ARC-4 method selector."""
+    hash_bytes = hashlib.sha512_256(signature.encode()).digest()
+    return hash_bytes[:4]
+
+# Example
+selector = get_selector("add(uint64,uint64)uint128")
+# Returns: b'\x8a\xa3\xb6\x1f' (hex: 8aa3b61f)
+```
+
+## Encoding Rules
+
+### Static vs Dynamic Types
+
+**Static types** have fixed size:
+- `uint<N>`, `byte`, `bool`, `ufixed<N>x<M>`
+- `address` (always 32 bytes)
+- `<type>[N]` where `type` is static
+- `(T1,...,TN)` where all Ti are static
+
+**Dynamic types** have variable size:
+- `string`, `<type>[]`
+- `<type>[N]` where `type` is dynamic
+- `(T1,...,TN)` where any Ti is dynamic
+
+### Tuple Encoding (Head + Tail)
+
+For a tuple `(T1, T2, ..., TN)`:
+
+1. **Head:** For each element:
+   - Static: encode value directly
+   - Dynamic: encode 2-byte offset to tail
+
+2. **Tail:** For each dynamic element:
+   - Encode the actual data
+
+```
+Example: (uint64, string, uint32, string)
+
+Head: [8 bytes uint64][2 byte offset1][4 bytes uint32][2 byte offset2]
+Tail: [string1 data][string2 data]
+
+Offsets point to start of each string in tail relative to head start.
+```
+
+### Boolean Packing
+
+Up to 8 consecutive booleans are packed into a single byte (MSB first):
+
+```
+(bool, bool, bool, uint64, bool, bool)
+First 3 bools: packed into 1 byte
+Then uint64: 8 bytes
+Last 2 bools: packed into 1 byte
+```
+
+## Method Invocation
+
+### Application Call Structure
+
+```
+ApplicationArgs[0]: Method selector (4 bytes)
+ApplicationArgs[1]: First argument (encoded)
+ApplicationArgs[2]: Second argument (encoded)
+...
+ApplicationArgs[15]: 15th+ arguments encoded as tuple (if >15 args)
+
+Accounts[]: Referenced accounts (for `account` args)
+ForeignAssets[]: Referenced assets (for `asset` args)
+ForeignApps[]: Referenced apps (for `application` args)
+```
+
+### Return Value
+
+Return values are logged with a specific prefix:
+
+```
+Log format: 0x151f7c75 + encoded_return_value
+
+The prefix 151f7c75 = SHA-512/256("return")[:4]
+```
+
+### Bare Methods
+
+Bare methods have no selector and no arguments. They are identified by `NumAppArgs == 0`.
+
+## Common Mistakes
+
+| Mistake | Problem | Fix |
+|---------|---------|-----|
+| Using native types in ABI | `def foo(x: int)` won't work | Use `arc4.UInt64` for arguments |
+| Returning reference type | `-> Account` is invalid | Return `arc4.Address` instead |
+| Wrong selector | Method not found | Verify signature matches exactly |
+| Missing transaction arg | Transaction not in group | Add preceding transaction |
+| Index out of bounds | Reference type index wrong | Check Accounts/Assets/Apps arrays |
+
+## References
+
+- [ARC-4 Specification](https://dev.algorand.co/arc-standards/arc-0004/)
+- [ARC-22 Read-only Methods](https://dev.algorand.co/arc-standards/arc-0022/)
+- [ARC-28 Event Logging](https://dev.algorand.co/arc-standards/arc-0028/)

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

@@ -0,0 +1,92 @@
+# Implement ARC Standards
+
+ARC (Algorand Request for Comments) standards define conventions for encoding, method calls, and application specifications on Algorand. This reference covers the most essential ARCs for smart contract development.
+
+## Key ARCs for Smart Contract Development
+
+| ARC | Purpose | When to Use |
+|-----|---------|-------------|
+| **ARC-4** | Application Binary Interface (ABI) | All smart contract method calls, type encoding |
+| **ARC-22** | Read-only method annotation | Methods that don't modify state |
+| **ARC-28** | Event logging specification | Emitting structured events |
+| **ARC-32** | Application Specification (deprecated) | Legacy app specs (use ARC-56 instead) |
+| **ARC-56** | Extended App Description | Modern app specs with full contract metadata |
+
+## ARC-4: The Foundation
+
+ARC-4 defines how to encode method calls and data types for Algorand smart contracts. It enables interoperability between contracts, clients, wallets, and explorers.
+
+### Method Signatures
+
+A method signature uniquely identifies a method: `name(arg_types)return_type`
+
+- No spaces between elements
+- No argument names, only types
+- `void` for no return value
+
+Examples:
+
+| Method | Signature |
+|--------|-----------|
+| `add(a: UInt64, b: UInt64) -> UInt128` | `add(uint64,uint64)uint128` |
+| `greet(name: String) -> String` | `greet(string)string` |
+| `transfer(to: Account, amt: UInt64) -> None` | `transfer(account,uint64)void` |
+| `process(p: PaymentTxn, d: Bytes) -> None` | `process(pay,byte[])void` |
+
+### Method Selector Calculation
+
+The method selector is the first 4 bytes of the SHA-512/256 hash of the method signature:
+
+```
+Method signature: add(uint64,uint64)uint128
+SHA-512/256 hash: 8aa3b61f0f1965c3a1cbfa91d46b24e54c67270184ff89dc114e877b1753254a
+Method selector: 8aa3b61f (first 4 bytes)
+```
+
+```python
+import hashlib
+
+def get_selector(signature: str) -> bytes:
+    """Calculate ARC-4 method selector."""
+    hash_bytes = hashlib.sha512_256(signature.encode()).digest()
+    return hash_bytes[:4]
+
+# Example
+selector = get_selector("add(uint64,uint64)uint128")
+# Returns: b'\x8a\xa3\xb6\x1f' (hex: 8aa3b61f)
+```
+
+## ARC-32 vs ARC-56
+
+| Feature | ARC-32 | ARC-56 |
+|---------|--------|--------|
+| **Status** | Deprecated | Current Standard |
+| **ARC-4 methods** | Yes | Yes |
+| **State schema** | Yes | Yes |
+| **Method hints** | Partial | Full |
+| **Named structs** | No | Yes |
+| **Default argument values** | Limited | Full support |
+| **Source code info** | No | Yes (optional) |
+| **Source maps** | No | Yes (optional) |
+| **ARC-28 events** | No | Yes |
+| **Bare action config** | Yes | Yes |
+| **Template variables** | No | Yes |
+| **Scratch variables** | No | Yes |
+
+**Use ARC-56** for all new projects. ARC-32 is maintained for legacy compatibility only.
+
+## Important Rules / Guidelines
+
+| Rule | Details |
+|------|---------|
+| **ARC-4 types only in ABI** | Use `arc4.UInt64`, `arc4.String`, etc. for method arguments and returns |
+| **Reference types as arguments only** | `account`, `asset`, `application` cannot be return types |
+| **15 argument limit** | Methods with 16+ args encode extras as a tuple in arg 15 |
+| **Return prefix** | Return values are logged with `151f7c75` prefix |
+| **Bare methods have no selector** | Bare calls use `NumAppArgs == 0` for routing |
+
+## References
+
+- [ARC-4 ABI Details](./implement-arc-standards-arc4.md) - Types, encoding rules, method invocation
+- [ARC-32/56 App Specs](./implement-arc-standards-arc32-arc56.md) - Application specification details
+- [ARC Standards](https://dev.algorand.co/arc-standards/) - Official ARC documentation

package/skills/algorand-development/references/search-algorand-examples-reference.md

@@ -0,0 +1,119 @@
+# Algorand Examples — WebFetch Reference
+
+Quick reference for fetching Algorand code examples using WebFetch with raw GitHub URLs.
+
+## Methods
+
+| Method | URL Pattern | Purpose |
+|--------|-------------|---------|
+| File contents | `https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}` | Read file contents (plain text) |
+| Directory listing | `https://api.github.com/repos/{owner}/{repo}/contents/{path}` | List directory entries (JSON) |
+| Knowledge docs | `get_knowledge_doc` (Algorand MCP) | Algorand developer documentation |
+
+## Fetching File Contents
+
+Use `raw.githubusercontent.com` to get file contents directly as plain text.
+
+**URL Format:**
+```
+https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}
+```
+
+**Examples:**
+
+```
+# Get a specific contract
+WebFetch url:https://raw.githubusercontent.com/algorandfoundation/puya-ts/main/examples/voting/contract.algo.ts
+
+# Get a test file
+WebFetch url:https://raw.githubusercontent.com/algorandfoundation/puya-ts/main/examples/voting/contract.spec.ts
+
+# Get devportal example
+WebFetch url:https://raw.githubusercontent.com/algorandfoundation/devportal-code-examples/main/projects/typescript-examples/contracts/HelloWorld/contract.algo.ts
+
+# Get a Python example
+WebFetch url:https://raw.githubusercontent.com/algorandfoundation/puya/main/examples/voting/contract.py
+
+# Get README or docs
+WebFetch url:https://raw.githubusercontent.com/algorandfoundation/algokit-utils-ts/main/README.md
+WebFetch url:https://raw.githubusercontent.com/algorandfoundation/algokit-utils-ts/main/CHANGELOG.md
+```
+
+## Listing Directory Contents
+
+Use `api.github.com` to list files in a directory.
+
+**URL Format:**
+```
+https://api.github.com/repos/{owner}/{repo}/contents/{path}
+```
+
+**Examples:**
+
+```
+# List examples directory
+WebFetch url:https://api.github.com/repos/algorandfoundation/puya-ts/contents/examples
+
+# List repo root
+WebFetch url:https://api.github.com/repos/algorandfoundation/devportal-code-examples/contents
+
+# List TypeScript contracts
+WebFetch url:https://api.github.com/repos/algorandfoundation/devportal-code-examples/contents/projects/typescript-examples/contracts
+
+# List Python contracts
+WebFetch url:https://api.github.com/repos/algorandfoundation/devportal-code-examples/contents/projects/python-examples/contracts
+
+# List specific branch
+WebFetch url:https://api.github.com/repos/algorandfoundation/puya-ts/contents/examples?ref=main
+```
+
+## Searching for Code Patterns
+
+For searching code across repositories, use web search:
+
+```
+# Search for BoxMap usage in TypeScript
+Web search: "BoxMap site:github.com/algorandfoundation language:typescript"
+
+# Search for inner transactions
+Web search: "itxn site:github.com/algorandfoundation"
+
+# Search for ARC-4 implementations
+Web search: "arc4 abimethod site:github.com/algorandfoundation"
+```
+
+## Using Knowledge Base (Algorand MCP)
+
+For Algorand developer documentation, use `get_knowledge_doc` or `list_knowledge_docs` from the Algorand MCP server (Remote Full or Local):
+
+```
+# List available documents in a category
+list_knowledge_docs { "prefix": "arcs" }
+
+# Get specific documentation
+get_knowledge_doc { "documents": ["arcs:specs:arc-0003.md"] }
+get_knowledge_doc { "documents": ["algokit:docs:get-started.md"] }
+```
+
+**Knowledge categories:** `arcs`, `sdks`, `algokit`, `algokit-utils`, `tealscript`, `puya`, `liquid-auth`, `python`, `developers`, `clis`, `nodes`, `details`
+
+## Priority Repositories
+
+| Repository | Path | Content |
+|------------|------|---------|
+| `devportal-code-examples` | `projects/typescript-examples/contracts/` | Beginner TypeScript |
+| `devportal-code-examples` | `projects/python-examples/contracts/` | Beginner Python |
+| `puya-ts` | `examples/` | Advanced TypeScript (voting, amm, auction) |
+| `puya` | `examples/` | Advanced Python |
+| `algokit-typescript-template` | `/` | Project template |
+| `algokit-utils-ts` | `src/` | Utility library |
+
+## Common Patterns Location
+
+| Pattern | Repository | Path |
+|---------|------------|------|
+| Box storage | devportal-code-examples | `contracts/BoxStorage/` |
+| BoxMap | puya-ts | `examples/voting/`, `examples/amm/` |
+| Inner transactions | devportal-code-examples | `contracts/` |
+| ARC-4 methods | puya-ts | `examples/hello_world_arc4/` |
+| State management | devportal-code-examples | `contracts/` |

package/skills/algorand-development/references/search-algorand-examples.md

@@ -0,0 +1,89 @@
+
+# Searching Algorand Examples
+
+Find working contract examples and code patterns from Algorand Foundation repositories using WebFetch with raw GitHub URLs.
+
+## Overview / Core Workflow
+
+1. Identify what pattern or example the user needs
+2. Use WebFetch to fetch raw file contents from priority GitHub repositories
+3. Search priority repositories first (devportal-code-examples, puya-ts)
+4. Retrieve the relevant file(s)
+5. Also fetch corresponding test files when applicable
+
+## How to proceed
+
+1. **Determine what you need:**
+   - Looking for a specific file → use WebFetch with the raw GitHub URL
+   - Need to browse a directory → use WebFetch with the GitHub API: `https://api.github.com/repos/{owner}/{repo}/contents/{path}`
+   - Looking for documentation → use `get_knowledge_doc` from Algorand MCP (Remote Full or Local)
+
+2. **Search priority repositories first:**
+
+   | Priority | Repository | Best For |
+   |----------|------------|----------|
+   | 1 | `algorandfoundation/devportal-code-examples` | Beginner-friendly patterns |
+   | 2 | `algorandfoundation/puya-ts` | Advanced TypeScript examples |
+   | 3 | `algorandfoundation/puya` | Python examples |
+   | 4 | `algorandfoundation/algokit-*` | Templates and utilities |
+
+3. **Fetch files with WebFetch:**
+
+   ```
+   # Get a specific file
+   WebFetch url:https://raw.githubusercontent.com/algorandfoundation/puya-ts/main/examples/voting/contract.algo.ts
+
+   # List directory contents (via GitHub API)
+   WebFetch url:https://api.github.com/repos/algorandfoundation/puya-ts/contents/examples
+
+   # Get a README or changelog
+   WebFetch url:https://raw.githubusercontent.com/algorandfoundation/algokit-utils-ts/main/CHANGELOG.md
+
+   # Get devportal examples
+   WebFetch url:https://raw.githubusercontent.com/algorandfoundation/devportal-code-examples/main/projects/typescript-examples/contracts/HelloWorld/contract.algo.ts
+   ```
+
+4. **Always fetch test files:**
+   - For any contract file, check for corresponding `*.spec.ts` or `*_test.py`
+   - Tests show how to call methods and verify behavior
+
+## Important Rules / Guidelines
+
+- **Search algorandfoundation first** — Official repos have vetted, up-to-date examples
+- **Always include test files** — They demonstrate correct usage patterns
+- **Use raw.githubusercontent.com** for file contents — faster and returns plain text
+- **Use api.github.com** for directory listings — returns JSON with file names and paths
+- **Check file paths in devportal-code-examples:**
+  - TypeScript: `projects/typescript-examples/contracts/`
+  - Python: `projects/python-examples/contracts/`
+- **Prefer puya-ts/examples for complex patterns** — Voting, AMM, auction examples are comprehensive
+
+## Raw GitHub URL Patterns
+
+```
+# File contents (plain text)
+https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}
+
+# Directory listing (JSON)
+https://api.github.com/repos/{owner}/{repo}/contents/{path}
+
+# Search code (JSON) - use web search as alternative
+https://api.github.com/search/code?q={query}+org:algorandfoundation+language:typescript
+```
+
+## Common Variations / Edge Cases
+
+| Scenario | Approach |
+|----------|----------|
+| Pattern not found in algorandfoundation | Use web search for broader GitHub results |
+| Need Python instead of TypeScript | Use `algorandfoundation/puya` instead of `puya-ts` |
+| Looking for deployment patterns | Check `algokit-*-template` repos |
+| Need ARC standard implementation | Use `get_knowledge_doc` with `arcs` category |
+| Need documentation | Use `get_knowledge_doc` or `list_knowledge_docs` from Algorand MCP |
+
+## References / Further Reading
+
+- [Tool Reference](./search-algorand-examples-reference.md)
+- [DevPortal Code Examples](https://github.com/algorandfoundation/devportal-code-examples)
+- [Puya TypeScript Examples](https://github.com/algorandfoundation/puya-ts/tree/main/examples)
+- [Algorand Developer Portal](https://dev.algorand.co/)