openclaw-algorand-plugin 0.5.0

package/skills/algorand-typescript/references/algorand-ts-migration-from-tealscript.md

@@ -0,0 +1,487 @@
+# Migrating TEALScript to Algorand TypeScript 1.0
+
+## Table of Contents
+
+- [Migration Checklist](#migration-checklist)
+- [Type Migration Table](#type-migration-table)
+- [Migrations](#migrations)
+  - [Add explicit imports](#add-explicit-imports)
+  - [EventLogger → emit](#replace-eventlogger-with-emit)
+  - [Box creation syntax](#update-box-creation-syntax)
+  - [Inner transactions](#refactor-inner-transactions)
+  - [sendMethodCall → arc4.abiCall](#replace-sendmethodcall-with-arc4abicall)
+  - [App creation with compileArc4](#use-arc4compilearc4-for-app-creation)
+  - [Static methods → compileArc4](#replace-static-methods-with-compilearc4)
+  - [Logic sigs](#update-logic-sigs)
+  - [Template variables](#move-template-variables)
+  - [Numeric type annotations](#add-explicit-type-annotations)
+  - [Typed literals → arc4.Uint](#replace-typed-literals-with-arc4uint)
+  - [Type casting](#replace-as-type-casts)
+  - [Array/object references](#use-clone-for-copies)
+
+## Migration Checklist
+
+Work through these changes when migrating from TEALScript to Algorand TypeScript 1.0:
+
+- [ ] **Explicit imports**: Replace global namespace with imports from `@algorandfoundation/algorand-typescript`
+- [ ] **Event logging**: Replace `EventLogger` with `emit()`
+- [ ] **Box creation**: Change `box.create(size)` to `box.create({ size })`
+- [ ] **Inner transactions**: Update to use `itxn` namespace methods
+- [ ] **Typed method calls**: Replace `sendMethodCall` with `arc4.abiCall`
+- [ ] **App creation**: Use `arc4.compileArc4()` before creating apps
+- [ ] **Compiled contract access**: Replace static methods with `arc4.compileArc4()` result
+- [ ] **Logic sigs**: Rename `logic()` to `program()`, add return statement
+- [ ] **Template variables**: Move outside class properties, use `TemplateVar<uint64>('NAME')`
+- [ ] **Type annotations**: Add `:uint64` to all arithmetic operations
+- [ ] **Numeric types**: Replace `uint256` literals with `arc4.Uint<256>` constructors
+- [ ] **Type casting**: Replace `as type` with constructor calls
+- [ ] **Array/object copies**: Use `clone()` function
+
+## Type Migration Table
+
+| TEALScript | Algorand TypeScript 1.0 |
+|------------|------------------------|
+| `EventLogger` | `emit` function |
+| `BoxKey` | `Box` |
+| `Txn` | `Transaction` |
+| `PayTxn` | `PaymentTxn` |
+| `AppCallTxn` | `ApplicationCallTxn` |
+| `KeyRegTxn` | `KeyRegistrationTxn` |
+| `OnCompletion` | `OnCompleteAction` |
+| `ecAdd`, `ecMultiply`, etc. | `ElipticCurve.add`, `ElipticCurve.multiply` |
+| `GlobalStateKey` | `GlobalState` |
+| `LocalStateKey` | `LocalState` |
+| `GlobalStateMap` | Not yet supported |
+| `LocalStateMap` | Not yet supported |
+| `isOptedInToApp`, `isOptedInToAsset` | `isOptedIn` |
+| `this.txn` | `Txn` |
+| `this.app` | `Global.currentApplicationAddress` |
+| `verify...Txn` | `assertMatch` |
+| `globals` | `Global` |
+| `StaticArray` | `FixedArray` |
+| `AppID` | `Application` |
+| `AssetID` | `Asset` |
+| `Address` | `Account` |
+| `throw Error('msg')` | `err('msg')` |
+
+## Migrations
+
+### Add explicit imports
+
+TEALScript injects types into global namespace. Algorand TypeScript requires explicit imports.
+
+**BEFORE - TEALScript**
+
+```ts
+import { LogicSig } from '@algorandfoundation/tealscript';
+
+class AppCaller extends LogicSig {
+  logic(): void {
+    assert(this.txn.applicationID === 1234); // No import needed
+  }
+}
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import {
+  LogicSig,
+  Txn,
+  assert,
+  uint64,
+  TemplateVar,
+} from '@algorandfoundation/algorand-typescript';
+
+class AppCaller extends LogicSig {
+  program(): boolean {
+    assert(Txn.applicationId.id === 1234);
+    return true;
+  }
+}
+```
+
+### Replace `EventLogger` with `emit()`
+
+**BEFORE - TEALScript**
+
+```ts
+class Swapper {
+  swap = new EventLogger<{
+    assetA: AssetID;
+    assetB: AssetID;
+  }>();
+
+  doSwap(a: AssetID, b: AssetID) {
+    this.swap.log({ assetA: a, assetB: b });
+  }
+}
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { uint64, emit, Contract } from '@algorandfoundation/algorand-typescript';
+
+type Swap = { assetA: uint64; assetB: uint64 };
+
+class Swapper extends Contract {
+  doSwap(a: uint64, b: uint64): void {
+    emit('swap', { assetA: a, assetB: b } as Swap);
+  }
+}
+
+// Alternative: infer event name from type
+type swap = { assetA: uint64; assetB: uint64 };
+
+class Swapper2 extends Contract {
+  doSwap(a: uint64, b: uint64) {
+    emit<swap>({ assetA: a, assetB: b });
+  }
+}
+```
+
+### Update box creation syntax
+
+**TEALScript**: `box.create(size)` or `box.create(size?)`
+
+**Algorand TypeScript**: `box.create({ size })` or `box.create(options?: { size?: uint64 })`
+
+Size is auto-determined for fixed-length types in both.
+
+### Refactor inner transactions
+
+#### Sending a single transaction
+
+**BEFORE - TEALScript**
+
+```ts
+sendAssetConfig({
+  total: 1000,
+  assetName: 'AST1',
+  unitName: 'unit',
+  decimals: 3,
+  manager: this.app.address,
+  reserve: this.app.address,
+});
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { itxn, Global, log } from '@algorandfoundation/algorand-typescript';
+
+const assetParams = itxn.assetConfig({
+  total: 1000,
+  assetName: 'AST1',
+  unitName: 'unit',
+  decimals: 3,
+  manager: Global.currentApplicationAddress,
+  reserve: Global.currentApplicationAddress,
+});
+
+const asset_txn = assetParams.submit();
+log(asset_txn.createdAsset.id);
+```
+
+#### Sending a transaction group
+
+**BEFORE - TEALScript**
+
+```ts
+this.pendingGroup.addAssetCreation({
+  configAssetTotal: 1000,
+  configAssetName: 'AST3',
+  configAssetUnitName: 'unit',
+  configAssetDecimals: 3,
+  configAssetManager: this.app.address,
+  configAssetReserve: this.app.address,
+});
+
+this.pendingGroup.addAppCall({
+  approvalProgram: APPROVE,
+  clearStateProgram: APPROVE,
+  fee: 0,
+});
+
+const appCreateTxn = this.lastInnerGroup[0];
+const asset3_txn = this.lastInnerGroup[1];
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { itxn, Global, assert, Bytes } from '@algorandfoundation/algorand-typescript';
+
+const assetParams = itxn.assetConfig({
+  total: 1000,
+  assetName: 'AST3',
+  unitName: 'unit',
+  decimals: 3,
+  manager: Global.currentApplicationAddress,
+  reserve: Global.currentApplicationAddress,
+});
+
+const appCreateParams = itxn.applicationCall({
+  approvalProgram: APPROVAL_PROGRAM,
+  clearStateProgram: CLEAR_STATE_PROGRAM,
+  fee: 0,
+});
+
+const [appCreateTxn, asset3_txn] = itxn.submitGroup(appCreateParams, assetParams);
+
+assert(appCreateTxn.createdApp, 'app is created');
+assert(asset3_txn.assetName === Bytes('AST3'));
+```
+
+### Replace `sendMethodCall` with `arc4.abiCall`
+
+**BEFORE - TEALScript**
+
+```ts
+const result = sendMethodCall<typeof Hello.prototype.greet>({
+  applicationID: app,
+  methodArgs: ['algo dev'],
+});
+
+assert(result === 'hello algo dev');
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { arc4, assert } from '@algorandfoundation/algorand-typescript';
+import type { HelloStubbed } from './HelloWorld.algo';
+
+// Option 1: type argument (supports type-only imports)
+const result = arc4.abiCall<typeof HelloStubbed.prototype.greet>({
+  appId: 1234,
+  args: ['algo dev'],
+}).returnValue;
+
+assert(result === 'hello algo dev');
+
+// Option 2: method property
+const result2 = arc4.abiCall({
+  method: Hello.prototype.greet,
+  appId: 1234,
+  args: ['algo dev'],
+}).returnValue;
+```
+
+### Use `arc4.compileArc4()` for app creation
+
+**BEFORE - TEALScript**
+
+```ts
+sendMethodCall<typeof Greeter.prototype.createApplication>({
+  clearStateProgram: Greeter.clearProgram(),
+  approvalProgram: Greeter.approvalProgram(),
+  globalNumUint: Greeter.schema.global.numUint,
+  methodArgs: ['hello'],
+});
+
+const app = this.itxn.createdApplicationId;
+
+const result = sendMethodCall<typeof Greeter.prototype.greet>({
+  applicationID: app,
+  methodArgs: ['world'],
+});
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { Contract, arc4, assert } from '@algorandfoundation/algorand-typescript';
+import Greeter from './Greeter.algo';
+
+// First compile the contract
+const compiled = arc4.compileArc4(Greeter);
+
+const app = arc4.abiCall({
+  method: compiled.call.createApplication,
+  args: ['hello'],
+  globalNumUint: compiled.globalUints,
+}).itxn.createdApp;
+
+const result = arc4.abiCall({
+  method: compiled.call.greet,
+  args: ['world'],
+  appId: app,
+}).returnValue;
+
+assert(result === 'hello world');
+```
+
+### Replace static methods with `compileArc4()`
+
+**BEFORE - TEALScript**
+
+```ts
+// Direct static method access
+Greeter.clearProgram();
+Greeter.approvalProgram();
+Greeter.schema.global.numUint;
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+// Use compiled object
+const compiled = arc4.compileArc4(Greeter);
+compiled.clearStateProgram;
+compiled.approvalProgram;
+compiled.globalUints;
+```
+
+### Update logic sigs
+
+**BEFORE - TEALScript**
+
+```ts
+class DangerousPaymentLsig extends LogicSig {
+  logic(amt: uint64) {
+    assert(this.txn.amount === amt);
+  }
+}
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { op, LogicSig, Txn } from '@algorandfoundation/algorand-typescript';
+
+class DangerousPaymentLsig extends LogicSig {
+  program() {
+    const amt = op.btoi(op.arg(0)); // Use op.arg() for arguments
+    return Txn.amount === amt; // Must return boolean or uint64
+  }
+}
+```
+
+### Move template variables
+
+**BEFORE - TEALScript**
+
+```ts
+class AppCaller extends LogicSig {
+  APP_ID = TemplateVar<AppID>();
+
+  logic(): void {
+    assert(this.txn.applicationID === this.APP_ID);
+  }
+}
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { LogicSig, Txn, TemplateVar, assert, uint64 } from '@algorandfoundation/algorand-typescript';
+
+// Template vars can be outside class
+const APP_ID = TemplateVar<uint64>('APP_ID');
+
+class AppCaller extends LogicSig {
+  program(): boolean {
+    assert(Txn.applicationId.id === APP_ID);
+    return true;
+  }
+}
+```
+
+### Add explicit type annotations
+
+TEALScript allows implicit `number` types. Algorand TypeScript requires explicit `uint64`.
+
+**BEFORE - TEALScript**
+
+```ts
+add(a: uint64, b: uint64): uint64 {
+  const sum = a + b; // Type inferred
+  return sum;
+}
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { uint64 } from '@algorandfoundation/algorand-typescript';
+
+add(a: uint64, b: uint64): uint64 {
+  const sum: uint64 = a + b; // Type required
+  return sum;
+}
+```
+
+### Replace typed literals with `arc4.Uint` constructors
+
+**BEFORE - TEALScript**
+
+```ts
+addOne(n: uint256): uint256 {
+  const one: uint256 = 1;
+  const sum = n + one;
+  return sum;
+}
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { arc4, biguint } from '@algorandfoundation/algorand-typescript';
+
+addOne(n: arc4.Uint<256>): arc4.Uint<256> {
+  // Use biguint for intermediate arithmetic to avoid overflow checks
+  const one = 1n;
+  const sum: biguint = n.asBigUint() + one;
+  return new arc4.Uint<256>(sum);
+}
+```
+
+**Best practice**: Use `biguint` for intermediate values, convert to `arc4.Uint` only when encoding.
+
+### Replace `as` type casts
+
+**BEFORE - TEALScript**
+
+```ts
+convertNumber(n: uint64): uint8 {
+  return n as uint8;
+}
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { uint64, arc4 } from '@algorandfoundation/algorand-typescript';
+
+convertNumber(n: uint64): arc4.Uint<8> {
+  return new arc4.Uint<8>(n); // Use constructor
+}
+```
+
+### Use `clone()` for array and object copies
+
+TEALScript allows mutable references. Algorand TypeScript requires explicit copies.
+
+**BEFORE - TEALScript**
+
+```ts
+const a: uint64[] = [1, 2, 3];
+const b = a;
+b.push(4);
+assert(a === b); // Same reference
+```
+
+**AFTER - Algorand TypeScript 1.0**
+
+```ts
+import { uint64, clone, assertMatch } from '@algorandfoundation/algorand-typescript';
+
+const a: uint64[] = [1, 2, 3];
+const b = clone(a); // Explicit copy
+b.push(4);
+
+assertMatch(a, [1, 2, 3]);
+assertMatch(b, [1, 2, 3, 4]); // Different arrays
+```

package/skills/algorand-typescript/references/algorand-ts-migration.md

@@ -0,0 +1,102 @@
+
+# Algorand TypeScript Migration
+
+Migrate smart contracts to Algorand TypeScript 1.0 from TEALScript or Algorand TypeScript Beta.
+
+## Migration Workflow
+
+### 1. Identify Source Language
+
+Determine whether the code is **TEALScript** or **Algorand TypeScript Beta**:
+
+| Indicator | TEALScript | Algorand TypeScript Beta |
+|-----------|------------|--------------------------|
+| Import source | `@algorandfoundation/tealscript` | `@algorandfoundation/algorand-typescript` |
+| Global types | Uses `assert`, `uint64` without imports | Requires explicit imports |
+| Event logging | `new EventLogger<...>()` | N/A |
+| Inner transactions | `sendAssetConfig({...})` | `itxn.assetConfig({...})` |
+| Logic sig method | `logic()` | `program()` |
+| Type syntax | `uint256`, `uint8` literals | `arc4.UintN<256>`, `arc4.UintN8` |
+
+### 2. Load Migration Guide
+
+Based on the source language, read the appropriate reference:
+
+- **From TEALScript**: Read [algorand-ts-migration-from-tealscript.md](./algorand-ts-migration-from-tealscript.md)
+- **From Algorand TypeScript Beta**: Read [algorand-ts-migration-from-beta.md](./algorand-ts-migration-from-beta.md)
+
+### 3. Execute Migration
+
+Follow the checklist in the loaded reference file. Apply transformations systematically:
+
+1. Start with imports and type renames (mechanical changes)
+2. Update syntax patterns (inner transactions, method calls)
+3. Add explicit type annotations where required
+4. Handle semantic changes (mutability, resource encoding)
+5. Rename test files if applicable
+
+### 4. Verify Migration
+
+After migration:
+- Ensure all imports resolve from `@algorandfoundation/algorand-typescript`
+- Verify no TypeScript errors remain
+- Run the Algorand TypeScript compiler to validate
+
+## Quick Reference
+
+### Common Import Pattern (1.0)
+
+```ts
+import {
+  Contract,
+  GlobalState,
+  LocalState,
+  Box,
+  BoxMap,
+  arc4,
+  uint64,
+  bytes,
+  Bytes,
+  Uint64,
+  assert,
+  err,
+  emit,
+  clone,
+  itxn,
+  gtxn,
+  Txn,
+  Global,
+  op,
+} from '@algorandfoundation/algorand-typescript';
+```
+
+### Key Type Changes
+
+| Old | New (1.0) |
+|-----|-----------|
+| `uint8`, `uint16`, `uint256` | `arc4.Uint<8>`, `arc4.Uint<16>`, `arc4.Uint<256>` |
+| `arc4.UintN64`, `arc4.UintN<N>` | `arc4.Uint64`, `arc4.Uint<N>` |
+| `arc4.UFixedNxM<N,M>` | `arc4.UFixed<N,M>` |
+| `MutableArray` | `ReferenceArray` |
+| `BoxRef` | `Box<bytes>` |
+| `Address` (TEALScript) | `Account` |
+| `AppID` (TEALScript) | `Application` |
+| `AssetID` (TEALScript) | `Asset` |
+
+### Key Function Changes
+
+| Old | New (1.0) |
+|-----|-----------|
+| `x.copy()` | `clone(x)` |
+| `arc4EncodedLength<T>()` | `sizeOf<T>()` |
+| `arc4.interpretAsArc4<T>(b)` | `arc4.convertBytes<T>(b, { strategy: 'validate' })` |
+| `x.native` | `x.asUint64()` or `x.asBigUint()` |
+| `sendMethodCall<T>({...})` | `arc4.abiCall({ method: T, ... })` |
+
+## Resources
+
+### references/
+
+- **[algorand-ts-migration-from-beta.md](./algorand-ts-migration-from-beta.md)**: Complete migration guide from Algorand TypeScript Beta to 1.0. Includes checklist of 13 breaking changes with before/after examples.
+
+- **[algorand-ts-migration-from-tealscript.md](./algorand-ts-migration-from-tealscript.md)**: Complete migration guide from TEALScript to Algorand TypeScript 1.0. Includes type migration table and 13 migration patterns with examples.

package/skills/algorand-typescript/references/algorand-typescript-syntax-methods-and-abi.md

@@ -0,0 +1,134 @@
+# Methods, ABI, and Lifecycle
+
+## Method Visibility
+
+By default, `@abimethod` decorators are NOT necessary. Visibility determines ABI exposure:
+
+| Visibility | Behavior |
+|------------|----------|
+| `public` | Automatically exposed as ABI method |
+| `private` | Becomes subroutine (internal only) |
+
+```typescript
+// Public = ABI method automatically
+public addTodo(text: string): uint64 { }
+
+// Private = subroutine
+private getTodoKey(account: bytes, todoId: uint64): string { }
+
+// Decorator only when needed for config
+@abimethod({ readonly: true })
+public getData(): [uint64, uint64, uint64] { }
+```
+
+**When to use `@abimethod()`**: Only when you need configuration like `{ readonly: true }`, `{ allowActions: 'OptIn' }`, etc.
+
+## Decorator Syntax
+
+ARC4 decorators MUST be called as functions with parentheses:
+
+```typescript
+// CORRECT
+@abimethod()
+public update(): string { }
+
+// INCORRECT - "Decorator function return type mismatch"
+@arc4.abimethod
+public update(): string { }
+```
+
+## Application Lifecycle Methods
+
+**PREFER convention-based methods** for lifecycle events. They are automatically routed based on OnCompletion action.
+
+| Method Name | When Called |
+|-------------|-------------|
+| `createApplication()` | Application creation |
+| `optInToApplication()` | OnCompletion is OptIn |
+| `closeOutOfApplication()` | OnCompletion is CloseOut |
+| `updateApplication()` | OnCompletion is UpdateApplication |
+| `deleteApplication()` | OnCompletion is DeleteApplication |
+
+```typescript
+export class TodoList extends Contract {
+  todos = LocalState<TodoListData>({ key: 'todos' })
+
+  // Convention-based: automatically routed on OptIn
+  public optInToApplication(): void {
+    const initialList = {
+      todos: [] as Todo[],
+      nextId: Uint64(1),
+    }
+    this.todos(Txn.sender).value = clone(initialList)
+  }
+
+  // Regular ABI methods for business logic
+  public addTodo(text: string): uint64 {
+    // ...
+  }
+}
+```
+
+## ABI Return Types
+
+Struct objects can be returned directly. Puya converts to ABI tuples automatically:
+
+```typescript
+// CORRECT: Return struct directly
+@abimethod({ readonly: true })
+public getData(): MyData {
+  const state = clone(this.appState.value)
+  return state  // Compiler converts to ABI tuple
+}
+
+// ALSO CORRECT: Return tuple explicitly
+@abimethod({ readonly: true })
+public getData(): [uint64, uint64, uint64] {
+  const state = clone(this.appState.value)
+  return [state.field1, state.field2, state.field3]
+}
+```
+
+## Type Definitions
+
+Use plain TypeScript types for storage, not ARC4 decorators:
+
+```typescript
+// CORRECT
+type MyData = { field1: uint64; field2: uint64 }
+
+// INCORRECT
+@arc4.abiTuple class MyData { }
+```
+
+## Generated Client Method Names
+
+### Convention-based Lifecycle Methods
+
+Convention-based methods like `optInToApplication()` are nested under their action type in generated clients:
+
+```typescript
+// Contract
+public optInToApplication(): void { }
+
+// Client call
+await client.send.optIn.optInToApplication({ args: [] })
+```
+
+### Decorator-based Opt-in Methods
+
+Methods with `@abimethod({ allowActions: 'OptIn' })` are also nested:
+
+```typescript
+// Contract
+@abimethod({ allowActions: 'OptIn' })
+public optIn(): void { }
+
+// CORRECT - nested under optIn
+await client.send.optIn.optIn({ args: [] })
+
+// INCORRECT
+await client.send.optIn({ args: [] })
+```
+
+**Recommendation**: Use convention-based `optInToApplication()` for better readability. Always check the generated client file to confirm exact method names.