openclaw-algorand-plugin 0.5.0

package/skills/algorand-typescript/references/algorand-typescript-syntax-reference.md

@@ -0,0 +1,58 @@
+# Algorand TypeScript Reference Index
+
+This skill includes detailed reference files for specific topics. Consult these when you need in-depth guidance.
+
+## Reference Files
+
+| File | Topics Covered |
+|------|----------------|
+| [types-and-values.md](./types-and-values.md) | AVM types, `uint64`, `bytes`, `clone()`, value semantics |
+| [storage.md](./storage.md) | GlobalState, LocalState, BoxMap, Box, MBR funding |
+| [methods-and-abi.md](./methods-and-abi.md) | Decorators, lifecycle methods, visibility, return types |
+| [transactions.md](./transactions.md) | Group transactions (gtxn), inner transactions (itxn) |
+
+## Quick Reference
+
+### Types
+
+| AVM Type | TypeScript | Creation |
+|----------|------------|----------|
+| uint64 | `uint64` | `Uint64(n)` |
+| bytes | `bytes` | `Bytes('...')` |
+| string | `string` | Native string |
+| bool | `boolean` | Native boolean |
+| biguint | `biguint` | `BigUint(n)` |
+
+### Storage
+
+| Type | Scope | Use Case |
+|------|-------|----------|
+| GlobalState | App-wide | Single values, app config |
+| LocalState | Per-account | User-specific data |
+| BoxMap | App-wide | Key-value storage, large data |
+| Box | App-wide | Single large value |
+
+### Method Decorators
+
+| Decorator | Purpose |
+|-----------|---------|
+| `@abimethod()` | ABI-callable method |
+| `@abimethod({ readonly: true })` | Read-only method |
+| `@baremethod({ onCreate: 'require' })` | Create handler |
+| `@baremethod({ onUpdate: 'require' })` | Update handler |
+
+### Clone Rules
+
+```typescript
+// Always clone when:
+const value = clone(this.storage.value)  // Reading from storage
+this.storage.value = clone(updated)       // Writing to storage
+for (const item of clone(array)) { }      // Iterating arrays
+const copy = clone(original)              // Copying complex types
+```
+
+## External Documentation
+
+- [Algorand TypeScript Documentation](https://dev.algorand.co/docs/get-started/algokit/typescript)
+- [Puya Compiler](https://github.com/algorandfoundation/puya-ts)
+- [AVM Specification](https://developer.algorand.org/docs/get-details/dapps/avm/)

package/skills/algorand-typescript/references/algorand-typescript-syntax-storage.md

@@ -0,0 +1,154 @@
+# Storage Patterns
+
+## Storage Types Overview
+
+| Storage | Scope | Who Pays MBR | Use Case |
+|---------|-------|--------------|----------|
+| `GlobalState` | App-wide | App account | Shared app data |
+| `LocalState` | Per-user | User (on opt-in) | Per-user data with opt-in |
+| `Box` | App-wide | App account | Large data, single key |
+| `BoxMap` | Per-key | App account | Per-user data without opt-in |
+
+## Storage Access Patterns
+
+### GlobalState
+
+```typescript
+import { GlobalState, clone } from '@algorandfoundation/algorand-typescript'
+
+export class MyContract extends Contract {
+  appState = GlobalState<MyData>({ key: 'state' })
+
+  public updateState(amount: uint64): void {
+    const state = clone(this.appState.value)
+    const updated = clone(state)
+    updated.counter = updated.counter + amount
+    this.appState.value = clone(updated)
+  }
+}
+```
+
+### LocalState (Requires Opt-in)
+
+```typescript
+import { LocalState, Txn, clone } from '@algorandfoundation/algorand-typescript'
+
+export class MyContract extends Contract {
+  userData = LocalState<UserData>({ key: 'user' })
+
+  public optInToApplication(): void {
+    const initial: UserData = { balance: Uint64(0) }
+    this.userData(Txn.sender).value = clone(initial)
+  }
+
+  public getBalance(): uint64 {
+    return clone(this.userData(Txn.sender).value).balance
+  }
+}
+```
+
+### BoxMap (No Opt-in Required)
+
+```typescript
+import { BoxMap, Account, clone } from '@algorandfoundation/algorand-typescript'
+
+export class MyContract extends Contract {
+  userBoxes = BoxMap<Account, UserData>({ keyPrefix: 'u' })
+
+  public createUser(user: Account): void {
+    const initial: UserData = { balance: Uint64(0) }
+    this.userBoxes(user).value = clone(initial)
+  }
+}
+```
+
+## Box Storage MBR (CRITICAL)
+
+Box storage increases the app account's Minimum Balance Requirement (MBR). The app account must be funded BEFORE boxes can be created.
+
+### MBR Formula
+
+```
+(2500 per box) + (400 * (box size + key size)) microAlgos per box
+```
+
+### Funding Pattern in deploy-config.ts
+
+```typescript
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+import { MyAppFactory } from '../artifacts/my_app/MyAppClient'
+
+export async function deploy() {
+  const algorand = AlgorandClient.fromEnvironment()
+  const deployer = await algorand.account.fromEnvironment('DEPLOYER')
+
+  const factory = algorand.client.getTypedAppFactory(MyAppFactory, {
+    defaultSender: deployer.addr,
+  })
+
+  const { appClient, result } = await factory.deploy({
+    onUpdate: 'append',
+    onSchemaBreak: 'append'
+  })
+
+  // MANDATORY: Fund app account if BoxMap is used
+  if (['create', 'replace'].includes(result.operationPerformed)) {
+    await algorand.send.payment({
+      amount: (1).algo(),  // Fund app account for box MBR
+      sender: deployer.addr,
+      receiver: appClient.appAddress,
+    })
+  }
+}
+```
+
+**Note**: `operationPerformed` values are `'create'`, `'replace'`, `'update'`, or `'append'`. Only fund on `'create'` or `'replace'` to avoid redundant funding.
+
+### Testing with BoxMap
+
+E2E tests using BoxMap require app account funding before first box operation:
+
+```typescript
+// Fund immediately after deployment in test setup
+const { client } = await deploy(testAccount)
+
+await localnet.algorand.send.payment({
+  amount: (1).algo(),
+  sender: testAccount,
+  receiver: client.appAddress,
+})
+
+// Now box operations will work
+await client.send.createUser({ args: [userAccount] })
+```
+
+## Choosing Storage Type
+
+| Scenario | Recommended | Reason |
+|----------|-------------|--------|
+| Per-user data, user pays | `LocalState` | User covers MBR on opt-in |
+| Per-user data, app pays | `BoxMap` | No opt-in needed, app funds MBR |
+| Shared app config | `GlobalState` | Simple, always available |
+| Large data (>128 bytes) | `Box` or `BoxMap` | No size limits like GlobalState |
+
+## Class Properties
+
+Cannot define class properties or constants. Only storage proxies allowed on contract classes:
+
+```typescript
+// CORRECT: Module-level constants
+const MAX_ITEMS: uint64 = Uint64(100)
+
+class MyContract extends Contract {
+  items = GlobalState<ItemList>({ key: 'items' })  // OK: storage proxy
+
+  public addItem(): void {
+    // Use MAX_ITEMS here
+  }
+}
+
+// INCORRECT: Class properties
+class MyContract extends Contract {
+  private readonly MAX_ITEMS: uint64 = Uint64(100)  // Compiler error
+}
+```

package/skills/algorand-typescript/references/algorand-typescript-syntax-transactions.md

@@ -0,0 +1,187 @@
+# Group and Inner Transactions
+
+## Group Transactions (gtxn)
+
+Access group transactions using typed `gtxn` functions with `uint64` indices:
+
+```typescript
+import { gtxn, Global, Uint64 } from '@algorandfoundation/algorand-typescript'
+
+// Verify group size
+assert(Global.groupSize === Uint64(3), 'Must be group of 3 transactions')
+
+// Access group transactions using typed functions
+const assetTransfer = gtxn.AssetTransferTxn(Uint64(0))  // First transaction
+const payment = gtxn.PaymentTxn(Uint64(1))              // Second transaction
+
+// Verify transaction properties
+assert(assetTransfer.sender.bytes === sellerBytes, 'Asset must come from seller')
+assert(assetTransfer.assetReceiver.bytes === buyer.bytes, 'Asset must go to buyer')
+assert(assetTransfer.xferAsset === asset, 'Asset ID mismatch')
+assert(payment.amount === listing.price, 'Payment amount mismatch')
+```
+
+**INCORRECT**: `const txn = gtxn[0]` — array indexing doesn't work.
+
+### Available Typed Functions
+
+| Function | Transaction Type |
+|----------|------------------|
+| `gtxn.PaymentTxn(n)` | Payment |
+| `gtxn.AssetTransferTxn(n)` | Asset transfer |
+| `gtxn.AssetConfigTxn(n)` | Asset configuration |
+| `gtxn.ApplicationCallTxn(n)` | Application call |
+| `gtxn.AssetFreezeTxn(n)` | Asset freeze |
+| `gtxn.KeyRegistrationTxn(n)` | Key registration |
+| `gtxn.Transaction(n)` | Untyped access |
+
+## Inner Transactions (itxn)
+
+### Method Selector Helper
+
+Use `methodSelector` to get the 4-byte ARC-4 method selector for inner app calls:
+
+```typescript
+import { methodSelector } from '@algorandfoundation/algorand-typescript/arc4'
+
+// Get selector from method signature
+const selector = methodSelector('transfer(address,uint64)void')
+
+// Use in inner app call
+itxn.applicationCall({
+  appId: targetApp,
+  appArgs: [selector, encodedArg1, encodedArg2],
+  fee: Uint64(0),
+}).submit()
+```
+
+### Method Names
+
+Inner transaction methods use **lowercase**:
+
+```typescript
+import { itxn, Global, Uint64 } from '@algorandfoundation/algorand-typescript'
+
+// CORRECT - lowercase
+itxn.payment({ ... }).submit()
+itxn.assetTransfer({ ... }).submit()
+
+// INCORRECT
+itxn.Payment({ ... })  // Wrong case
+```
+
+### Application Address
+
+Use `Global.currentApplicationAddress`, not `this.appAddress()`:
+
+```typescript
+// CORRECT
+assert(payment.receiver.bytes === Global.currentApplicationAddress.bytes)
+
+// INCORRECT
+assert(payment.receiver.bytes === this.appAddress().bytes)
+```
+
+### Account from Bytes
+
+When storing Account as bytes and converting back for inner transactions:
+
+```typescript
+// Store Account as bytes (required for GlobalState/BoxMap)
+const escrow = clone(this.escrow.value)
+const sellerBytes = escrow.seller  // bytes stored in state
+
+// Convert bytes to Account for inner transaction
+itxn.payment({
+  receiver: Account(sellerBytes),  // Convert bytes to Account
+  amount: escrow.amount,
+  fee: Uint64(0),
+}).submit()
+```
+
+### Fee Pooling (CRITICAL)
+
+Always set `fee: Uint64(0)` for inner transactions. The app call sender covers fees through fee pooling:
+
+```typescript
+itxn.payment({
+  receiver: Account(sellerBytes),
+  amount: escrow.amount,
+  fee: Uint64(0),  // Caller covers fees
+}).submit()
+```
+
+This prevents app account drain attacks where malicious callers force the app to pay fees.
+
+### Composing Multiple Inner Transactions
+
+Use `itxnCompose` for submitting multiple inner transactions atomically:
+
+```typescript
+import { itxn, itxnCompose, Global, Account, Uint64 } from '@algorandfoundation/algorand-typescript'
+
+// Submit multiple inner transactions as a group
+itxnCompose.begin()
+
+itxnCompose.next(
+  itxn.payment({
+    receiver: Account(recipientBytes),
+    amount: Uint64(100_000),
+    fee: Uint64(0),
+  })
+)
+
+itxnCompose.next(
+  itxn.assetTransfer({
+    xferAsset: assetId,
+    assetReceiver: Account(recipientBytes),
+    assetAmount: Uint64(50),
+    fee: Uint64(0),
+  })
+)
+
+itxnCompose.submit()
+```
+
+**Note**: `itxnCompose.begin()` starts a new group, `itxnCompose.next()` adds transactions, and `itxnCompose.submit()` sends them all atomically.
+
+## Asset Type
+
+`Asset` constructor takes `uint64` directly:
+
+```typescript
+// CORRECT
+const asset = Asset(assetId)  // if assetId is already uint64
+const asset = Asset(Uint64(123))
+
+// INCORRECT
+const asset = Asset(123)  // number literal
+const asset = Asset({ id: 123 })  // object
+```
+
+## Complete Example: Escrow Release
+
+```typescript
+import { 
+  itxn, gtxn, Global, Account, Uint64, assert, clone 
+} from '@algorandfoundation/algorand-typescript'
+
+public releaseEscrow(): void {
+  const escrow = clone(this.escrowData.value)
+  
+  // Verify the payment came to app
+  assert(Global.groupSize === Uint64(2), 'Expected 2 txns')
+  const payment = gtxn.PaymentTxn(Uint64(0))
+  assert(
+    payment.receiver.bytes === Global.currentApplicationAddress.bytes,
+    'Payment must go to app'
+  )
+  
+  // Send funds to seller via inner transaction
+  itxn.payment({
+    receiver: Account(escrow.seller),
+    amount: escrow.amount,
+    fee: Uint64(0),  // Fee pooling
+  }).submit()
+}
+```

package/skills/algorand-typescript/references/algorand-typescript-syntax-types-and-values.md

@@ -0,0 +1,150 @@
+# AVM Types and Value Semantics
+
+## Basic AVM Types
+
+| Type | Description | Constructor |
+|------|-------------|-------------|
+| `uint64` | 64-bit unsigned integer | `Uint64()` |
+| `bytes` | Byte array | `Bytes()` |
+| `bigint` | Up to 512-bit unsigned integer | `BigUInt` |
+| `string` | UTF-8 string | Native strings |
+| `bool` | Boolean | `true`/`false` |
+
+## Type Mappings
+
+AVM types don't map to JavaScript primitives:
+- JavaScript `number` is signed and unbounded; AVM `uint64` is 64-bit unsigned
+- JavaScript `Uint8Array`/`ArrayBuffer` don't exist; use `bytes`
+
+## Objects and Arrays
+
+**Plain TypeScript objects** are supported and mutable:
+```typescript
+type Point = { x: uint64; y: uint64 }
+```
+
+**Plain TypeScript arrays** are supported and mutable:
+```typescript
+const values: uint64[] = []
+const items: Array<uint64> = []
+```
+
+**Prefer native types over ARC4**: Plain objects and arrays are more efficient for computations and mutations than `arc4.StaticArray`, `arc4.DynamicArray`, `arc4.Struct`.
+
+## Numbers (CRITICAL)
+
+Puya rejects JavaScript `number` entirely:
+
+```typescript
+// CORRECT
+const amount: uint64 = Uint64(20)
+const total: uint64 = amount + Uint64(100)
+return this.counter.value  // Safe if already uint64
+
+// INCORRECT - Compiler error
+const amount = 20
+const total = amount + 100
+```
+
+**Arithmetic type inference**: Explicitly type results to avoid inference as `number`:
+
+```typescript
+// CORRECT
+const timeout: uint64 = Global.latestTimestamp + timeoutSeconds
+
+// INCORRECT - May infer as number
+const timeout = Global.latestTimestamp + timeoutSeconds
+```
+
+## String Operations
+
+`string.length` is NOT supported. Use equality checks:
+
+```typescript
+// CORRECT
+assert(text !== '', 'Text cannot be empty')
+
+// INCORRECT - Compiler error
+assert(text.length > 0, 'Text cannot be empty')
+assert(text.length <= 200, 'Text too long')
+```
+
+## Value Semantics (CRITICAL)
+
+AVM uses value semantics only. Use `clone()` for complex types (structs, arrays, objects):
+
+```typescript
+import { clone } from '@algorandfoundation/algorand-typescript'
+
+// GlobalState: clone on read, modify, write
+const state = clone(this.appState.value)  // Clone on read
+const updated = clone(state)              // Clone for modification
+updated.field1 = updated.field1 + amount
+this.appState.value = clone(updated)      // Clone on write
+
+// Box: reads OK without clone, writes need clone
+const stored = this.someBox.value         // Read OK
+const copy = clone(stored)                // Clone for modification
+copy.someField = copy.someField + amount
+this.someBox.value = clone(copy)          // Clone before write
+```
+
+**When to clone**:
+- ALWAYS when reading from `GlobalState`, `Box`, `BoxMap`, `LocalState` with complex types
+- ALWAYS when assigning structs/arrays to storage
+- Even if already cloned, clone again when assigning to storage
+
+**Exception**: Primitive types (`uint64`, `bytes`, `string`, `bool`) stored directly (not in structs) do NOT require `clone()`.
+
+## Union Types (Not Supported)
+
+Cannot use union types like `Item | null` or `string | uint64`:
+
+```typescript
+// CORRECT - Use boolean flags
+let found = false
+let foundItem: Item = { /* default values */ }
+for (const item of clone(items)) {
+  if (matches(item)) {
+    foundItem = clone(item)
+    found = true
+    break
+  }
+}
+assert(found, 'Item not found')
+return foundItem
+
+// INCORRECT - Compiler error
+let foundItem: Item | null = null
+let value: string | uint64 = someValue
+```
+
+## Array Operations
+
+- **AVOID**: `forEach` — use `for...of`
+- **AVOID**: `splice` on dynamic arrays — opcode-heavy
+- **PREFER**: `StaticArray<uint64, N>` for fixed-size arrays
+- **AVOID**: Nested dynamic types (`uint64[][]`) — encode as tuples
+
+**Critical array rules**:
+- Functions cannot mutate passed arrays
+- Cannot specify array lengths with square brackets (`number[10]` invalid)
+- Arrays in object literals must be cloned: `{ todos: clone(array) }`
+- Clone arrays before iterating: `for (const item of clone(array))`
+- Loop indices must be `uint64`, not `number`:
+
+```typescript
+let index = Uint64(0)
+for (const item of clone(array)) {
+  // use index
+  index = index + Uint64(1)
+}
+```
+
+## Unavailable APIs
+
+These JavaScript APIs are NOT supported (AVM constraints):
+- `Uint8Array` / `ArrayBuffer`
+- Object methods (`.keys()`, `.values()`, etc.)
+- Array length via square brackets
+- Standard JavaScript APIs

package/skills/algorand-typescript/references/algorand-typescript-syntax.md

@@ -0,0 +1,84 @@
+
+# Algorand TypeScript Rules
+
+Critical syntax rules for Algorand TypeScript (PuyaTs) that prevent compiler errors and runtime failures.
+
+**File Extension**: Contract files must use `.algo.ts` extension (e.g., `Counter.algo.ts`).
+
+## Overview / Core Workflow
+
+1. Identify the syntax issue or pattern needed
+2. Apply the correct AVM-compatible pattern
+3. Use `clone()` for complex types
+4. Verify no union types or JavaScript `number`
+
+## How to proceed
+
+1. **Check the most critical rules below**
+2. **Consult detailed reference files** for specific topics
+3. **Apply the correct pattern** with proper AVM types
+4. **Build to verify**: `algokit project run build`
+
+## Important Rules / Guidelines
+
+### Numbers: No JavaScript `number`
+
+```typescript
+// CORRECT
+const amount: uint64 = Uint64(20)
+const total: uint64 = amount + Uint64(100)
+
+// INCORRECT - Compiler error
+const amount = 20
+```
+
+**Numeric limits**: Algorand TypeScript supports integers up to 2^512. Use `biguint` for values exceeding uint64 (2^64 - 1).
+
+### Value Semantics: Always `clone()`
+
+```typescript
+import { clone } from '@algorandfoundation/algorand-typescript'
+
+const state = clone(this.appState.value)     // Read: clone
+const updated = clone(state)                  // Modify: clone
+this.appState.value = clone(updated)          // Write: clone
+```
+
+### No Union Types
+
+```typescript
+// CORRECT - Use boolean flags
+let found = false
+let foundItem: Item = { /* defaults */ }
+
+// INCORRECT - Compiler error
+let foundItem: Item | null = null
+```
+
+### Arrays: Clone Before Iterating
+
+```typescript
+// CORRECT
+for (const item of clone(array)) { }
+```
+
+## Common Variations / Edge Cases
+
+| Topic | Rule |
+|-------|------|
+| Numbers | Use `uint64` + `Uint64()`, never `number` |
+| Strings | No `.length`; use `text !== ''` for empty check |
+| Storage | Clone on read AND write for complex types |
+| Arrays | Clone before iterating; indices must be `uint64` |
+| Classes | No class properties; use module-level constants |
+| Methods | Public = ABI method; private = subroutine |
+
+## References / Further Reading
+
+Detailed rules by topic:
+
+- [Types and Values](./algorand-typescript-syntax-types-and-values.md) — AVM types, numbers, clone(), value semantics
+- [Storage](./algorand-typescript-syntax-storage.md) — GlobalState, LocalState, BoxMap, MBR funding
+- [Methods and ABI](./algorand-typescript-syntax-methods-and-abi.md) — Decorators, lifecycle methods, visibility
+- [Transactions](./algorand-typescript-syntax-transactions.md) — Group transactions (gtxn), inner transactions (itxn)
+- [Full Reference Index](./algorand-typescript-syntax-reference.md)

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

@@ -0,0 +1,52 @@
+# TypeScript Smart Contract Repository and Pattern Reference
+
+TypeScript-specific repositories, paths, and patterns for building Algorand smart contracts with PuyaTs.
+
+## Priority Repositories
+
+### Priority 1: DevPortal Code Examples (TypeScript)
+**Repository:** `algorandfoundation/devportal-code-examples`
+**Path:** `projects/typescript-examples/contracts/`
+
+Common contract patterns available:
+- `BoxStorage/` -- Box, BoxMap, BoxRef patterns
+- State management examples (GlobalState, LocalState)
+- ARC-4 method examples
+- Inner transaction patterns
+
+Always retrieve corresponding test files alongside contracts.
+
+### Priority 2: Puya-TS Compiler Examples
+**Repository:** `algorandfoundation/puya-ts`
+**Path:** `examples/`
+
+Key examples:
+- `hello_world_arc4/` -- Basic ARC-4 contract structure
+- `voting/` -- State management and complex logic
+- `amm/` -- Advanced patterns (multi-asset, inner transactions)
+- Search for `itxn` patterns for inner transaction examples
+
+### Priority 3: AlgoKit TypeScript Template
+**Repository:** `algorandfoundation/algokit-typescript-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 | `devportal-code-examples/projects/typescript-examples/contracts/BoxStorage/` |
+| Inner transactions | `puya-ts/examples/` (search for itxn usage) |
+| ARC-4 methods | `puya-ts/examples/hello_world_arc4/` |
+| State management | `devportal-code-examples/projects/typescript-examples/contracts/` |
+| AMM / DeFi | `puya-ts/examples/amm/` |
+| Voting | `puya-ts/examples/voting/` |
+
+## Supporting Repositories
+
+- `algorandfoundation/algokit-cli` -- CLI tool reference
+- `algorandfoundation/algokit-client-generator-ts` -- Generated client patterns
+- `algorandfoundation/algokit-utils-ts` -- Utility functions for deployment and testing