@goplausible/openclaw-algorand-plugin 0.5.0

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

@@ -0,0 +1,126 @@
+# ARC-4 Implementation (TypeScript)
+
+This reference covers implementing and calling ARC-4 methods in Algorand TypeScript.
+
+## Table of Contents
+
+- [Using ARC-4 Types in Contracts](#using-arc-4-types-in-contracts)
+- [Calling ARC-4 Methods from Clients](#calling-arc-4-methods-from-clients)
+- [Common ARC-4 Patterns](#common-arc-4-patterns)
+  - [Structs](#structs)
+  - [Arrays](#arrays)
+  - [Bare Methods](#bare-methods)
+
+## Using ARC-4 Types in Contracts
+
+```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)
+  }
+}
+```
+
+## Calling ARC-4 Methods from Clients
+
+```typescript
+// Using AlgoKit Utils typed client
+const result = await client.send.add({
+  args: { a: 10n, b: 20n }
+})
+
+// Access return value
+const sum = result.return  // BigInt
+```
+
+## Common ARC-4 Patterns
+
+### Structs
+
+```typescript
+import { Contract } from '@algorandfoundation/algorand-typescript'
+import { abimethod, Struct, UInt64, Bool, Str, Address } from '@algorandfoundation/algorand-typescript/arc4'
+
+class UserInfo extends Struct<{
+  name: Str
+  balance: UInt64
+  active: Bool
+}> {}
+
+class MyContract extends Contract {
+  @abimethod()
+  getUser(addr: Address): UserInfo {
+    return new UserInfo({
+      name: new Str('Alice'),
+      balance: new UInt64(1000),
+      active: new Bool(true),
+    })
+  }
+}
+```
+
+### Arrays
+
+```typescript
+import { Contract } from '@algorandfoundation/algorand-typescript'
+import { abimethod, UInt64, DynamicArray, StaticArray } from '@algorandfoundation/algorand-typescript/arc4'
+
+class MyContract extends Contract {
+  @abimethod()
+  processList(items: DynamicArray<UInt64>): UInt64 {
+    let total = 0n
+    for (const item of items) {
+      total += item.native
+    }
+    return new UInt64(total)
+  }
+}
+```
+
+### Bare Methods
+
+```typescript
+import { Contract } from '@algorandfoundation/algorand-typescript'
+import { baremethod } from '@algorandfoundation/algorand-typescript/arc4'
+
+class MyContract extends Contract {
+  @baremethod({ create: 'require' })
+  create(): void {
+    // Called on app creation with no args
+  }
+
+  @baremethod({ allowActions: ['OptIn'] })
+  optIn(): void {
+    // Called on OptIn with no args
+  }
+}
+```
+
+Bare calls are identified by `NumAppArgs == 0`.

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

@@ -0,0 +1,44 @@
+# Implement ARC Standards (TypeScript)
+
+This reference covers implementing ARC standards in Algorand TypeScript 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
+
+```typescript
+import { Contract } from '@algorandfoundation/algorand-typescript'
+import { abimethod, UInt64, UInt128 } from '@algorandfoundation/algorand-typescript/arc4'
+
+class Calculator extends Contract {
+  @abimethod()
+  add(a: UInt64, b: UInt64): UInt128 {
+    return new UInt128(a.native + b.native)
+  }
+}
+```
+
+## Using Typed Clients with ARC-56
+
+```typescript
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+import { CalculatorFactory } from './clients/Calculator'
+
+const algorand = AlgorandClient.defaultLocalNet()
+
+// Deploy new contract
+const factory = algorand.client.getTypedAppFactory(CalculatorFactory)
+const { appClient } = await factory.deploy({
+  onSchemaBreak: 'replace',
+  onUpdate: 'update',
+})
+
+// Call methods with full type safety
+const result = await appClient.send.add({
+  args: { a: 10n, b: 20n }
+})
+console.log(result.return) // BigInt: 30n
+```
+
+## References
+
+- [TypeScript ARC-4 Implementation](./implement-arc-standards-arc4.md) - ARC-4 types, contracts, and client calls
+- [TypeScript ARC-32/56 Client Usage](./implement-arc-standards-arc32-arc56.md) - App specs, typed clients, and state access

package/skills/algorand-typescript/references/test-smart-contracts-examples.md

@@ -0,0 +1,245 @@
+# Canonical Test Examples
+
+Real-world examples from [algorandfoundation/devportal-code-examples](https://github.com/algorandfoundation/devportal-code-examples/tree/main/projects/typescript-examples/contracts).
+
+## HelloWorld - Basic Contract
+
+**Source:** [HelloWorld/contract.algo.e2e.spec.ts](https://github.com/algorandfoundation/devportal-code-examples/blob/main/projects/typescript-examples/contracts/HelloWorld/contract.algo.e2e.spec.ts)
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+import { algorandFixture } from '@algorandfoundation/algokit-utils/testing'
+import { Address } from 'algosdk'
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest'
+import { HelloWorldFactory } from '../artifacts/clients/HelloWorld/HelloWorldClient'
+
+describe('HelloWorld contract', () => {
+  const localnet = algorandFixture()
+
+  beforeAll(() => {
+    Config.configure({ debug: true })
+  })
+  beforeEach(localnet.newScope)
+
+  const deploy = async (account: Address) => {
+    const factory = localnet.algorand.client.getTypedAppFactory(HelloWorldFactory, {
+      defaultSender: account,
+    })
+    const { appClient } = await factory.deploy({
+      onUpdate: 'append',
+      onSchemaBreak: 'append',
+      suppressLog: true,
+    })
+    return { client: appClient }
+  }
+
+  test('say hello', async () => {
+    const { testAccount } = localnet.context
+    const { client } = await deploy(testAccount)
+
+    const result = await client
+      .newGroup()
+      .sayHello({ args: { firstName: 'Silvio', lastName: 'Micali' } })
+      .simulate()
+
+    expect(result.returns[0]).toBe('Hello Silvio Micali')
+  })
+})
+```
+
+## BoxStorage - Boxes and BoxMaps
+
+**Source:** [BoxStorage/contract.algo.e2e.test.ts](https://github.com/algorandfoundation/devportal-code-examples/blob/main/projects/typescript-examples/contracts/BoxStorage/contract.algo.e2e.test.ts)
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+import { algorandFixture } from '@algorandfoundation/algokit-utils/testing'
+import { Address, ABIUintType } from 'algosdk'
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest'
+import { BoxStorageFactory } from '../artifacts/clients/BoxStorage/BoxStorageClient'
+
+describe('BoxStorage contract', () => {
+  const localnet = algorandFixture()
+
+  beforeAll(() => {
+    Config.configure({ debug: true })
+  })
+  beforeEach(localnet.newScope)
+
+  const deploy = async (account: Address) => {
+    const factory = localnet.algorand.client.getTypedAppFactory(BoxStorageFactory, {
+      defaultSender: account,
+    })
+    const { appClient } = await factory.deploy({
+      onUpdate: 'append',
+      onSchemaBreak: 'append',
+      suppressLog: true,
+    })
+    return { client: appClient }
+  }
+
+  // CRITICAL: Fund app account before any box operations
+  const fundContract = async (sender: Address, receiver: Address) => {
+    await localnet.algorand.send.payment({
+      amount: (1).algo(),
+      sender,
+      receiver,
+    })
+  }
+
+  // Helper for BoxMap references with uint64 keys
+  function createBoxReference(appId: bigint, prefix: string, key: bigint) {
+    const uint64Type = new ABIUintType(64)
+    const encodedKey = uint64Type.encode(key)
+    const boxName = new Uint8Array([...new TextEncoder().encode(prefix), ...encodedKey])
+    return { appId, name: boxName }
+  }
+
+  test('set and read box value', async () => {
+    const { testAccount } = localnet.context
+    const { client } = await deploy(testAccount)
+
+    // Fund BEFORE box operations
+    await fundContract(testAccount, client.appAddress)
+
+    await client
+      .newGroup()
+      .setBox({ args: { valueInt: 42n }, boxReferences: ['boxInt'] })
+      .send()
+
+    const boxValue = await client.state.box.boxInt()
+    expect(boxValue).toBe(42n)
+  })
+
+  test('set and read BoxMap', async () => {
+    const { testAccount } = localnet.context
+    const { client } = await deploy(testAccount)
+
+    await fundContract(testAccount, client.appAddress)
+
+    await client
+      .newGroup()
+      .setBoxMap({
+        args: { key: 1n, value: 'Hello' },
+        boxReferences: [createBoxReference(client.appId, 'boxMap', 1n)],
+      })
+      .send()
+
+    const value = await client.getBoxMap({ args: { key: 1n } })
+    expect(value).toBe('Hello')
+  })
+})
+```
+
+## LocalStorage - Opt-in and Local State
+
+**Source:** [LocalStorage/contract.algo.e2e.spec.ts](https://github.com/algorandfoundation/devportal-code-examples/blob/main/projects/typescript-examples/contracts/LocalStorage/contract.algo.e2e.spec.ts)
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+import { algorandFixture } from '@algorandfoundation/algokit-utils/testing'
+import { Address } from 'algosdk'
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest'
+import { LocalStorageFactory } from '../artifacts/clients/LocalStorage/LocalStorageClient'
+
+describe('LocalStorage contract', () => {
+  const localnet = algorandFixture()
+
+  beforeAll(() => {
+    Config.configure({ debug: true })
+  })
+  beforeEach(localnet.newScope)
+
+  const deploy = async (account: Address) => {
+    const factory = localnet.algorand.client.getTypedAppFactory(LocalStorageFactory, {
+      defaultSender: account,
+    })
+    const { appClient } = await factory.deploy({
+      onUpdate: 'append',
+      onSchemaBreak: 'append',
+      suppressLog: true,
+    })
+    return { client: appClient }
+  }
+
+  test('opt in and read local state', async () => {
+    const { testAccount } = localnet.context
+    const { client } = await deploy(testAccount)
+
+    // MUST opt in before accessing local state
+    await client.newGroup().optIn.optInToApplication().send()
+
+    const result = await client.newGroup().readLocalState().simulate()
+    expect(result.returns![0]).toBeDefined()
+  })
+
+  test('write and read local state', async () => {
+    const { testAccount } = localnet.context
+    const { client } = await deploy(testAccount)
+
+    await client.newGroup().optIn.optInToApplication().send()
+
+    await client
+      .newGroup()
+      .writeLocalState({
+        args: {
+          valueString: 'Hello',
+          valueBool: true,
+          valueAccount: testAccount.addr.toString(),
+        },
+      })
+      .send()
+
+    const result = await client.newGroup().readLocalState().simulate()
+    expect(result.returns![0]![3]).toBe('Hello')
+  })
+})
+```
+
+## StructInBox - Struct Returns as Tuples
+
+**Source:** [StructInBox/contract.algo.e2e.spec.ts](https://github.com/algorandfoundation/devportal-code-examples/blob/main/projects/typescript-examples/contracts/StructInBox/contract.algo.e2e.spec.ts)
+
+```typescript
+test('create and get user struct', async () => {
+  const { testAccount } = localnet.context
+  const { client } = await deploy(testAccount)
+
+  await fundContract(testAccount, client.appAddress)
+
+  const testUser = {
+    id: 1n,
+    name: 'TestUser',
+    age: 25n,
+  }
+
+  await client.send.createNewUser({
+    args: { id: 1n, user: testUser },
+    boxReferences: [createBoxReference(client.appId, 'users', 1n)],
+  })
+
+  const { returns } = await client.send.getUser({
+    args: { id: 1n },
+    boxReferences: [createBoxReference(client.appId, 'users', 1n)],
+  })
+
+  // CRITICAL: Struct returns are tuples, access by index
+  const [id, name, age] = returns?.[0]?.returnValue as [bigint, string, bigint]
+  expect(id).toBe(testUser.id)
+  expect(name).toBe(testUser.name)
+  expect(age).toBe(testUser.age)
+})
+```
+
+## Key Patterns Summary
+
+| Pattern | Code |
+|---------|------|
+| Deploy | `const { appClient } = await factory.deploy({ onUpdate: 'append', onSchemaBreak: 'append' })` |
+| Send method | `await client.send.methodName({ args: { ... } })` |
+| Chain methods | `await client.newGroup().method1().method2().send()` |
+| Simulate | `await client.newGroup().method().simulate()` |
+| Fund app | `await localnet.algorand.send.payment({ amount: (1).algo(), sender, receiver: client.appAddress })` |
+| Opt-in | `await client.newGroup().optIn.optInToApplication().send()` |
+| Box reference | `boxReferences: ['boxName']` or `boxReferences: [createBoxReference(...)]` |
+| Struct return | `const [field1, field2] = result.return as [Type1, Type2]` |

package/skills/algorand-typescript/references/test-smart-contracts-unit-tests.md

@@ -0,0 +1,147 @@
+# Unit Testing Guide
+
+**Only use unit tests if the user explicitly requests them.** Integration tests (E2E) are the default and recommended approach.
+
+## When to use unit tests
+
+- User explicitly says "unit test" or "offline test"
+- Testing pure contract logic without network interaction
+- Fast iteration during contract development
+
+## File naming
+
+- Unit tests: `contract.algo.spec.ts` (no `.e2e.` in the name)
+
+## Basic Setup
+
+```typescript
+import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
+import { describe, expect, it, afterEach } from 'vitest'
+import MyContract from './contract.algo'
+
+describe('MyContract unit tests', () => {
+  const ctx = new TestExecutionContext()
+
+  afterEach(() => {
+    ctx.reset()
+  })
+
+  it('should call method directly', () => {
+    const contract = ctx.contract.create(MyContract)
+
+    // Call methods directly - no ABI encoding
+    const result = contract.myMethod('arg1', 42n)
+
+    expect(result).toBe('expected value')
+  })
+})
+```
+
+## Key Differences from E2E Tests
+
+| Aspect | E2E Tests | Unit Tests |
+|--------|-----------|------------|
+| **Framework** | `algorandFixture` | `TestExecutionContext` |
+| **Network** | LocalNet | Emulated AVM |
+| **Contract access** | Via typed client | Direct instance |
+| **Method calls** | `client.send.method({ args: {...} })` | `contract.method(arg1, arg2)` |
+| **Struct returns** | Tuples `[field1, field2]` | Object properties `result.field1` |
+| **File naming** | `*.e2e.spec.ts` | `*.spec.ts` |
+
+## Canonical Example
+
+**Source:** [HelloWorld/contract.algo.spec.ts](https://github.com/algorandfoundation/devportal-code-examples/blob/main/projects/typescript-examples/contracts/HelloWorld/contract.algo.spec.ts)
+
+```typescript
+import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
+import { describe, expect, it } from 'vitest'
+import HelloWorld from './contract.algo'
+
+describe('HelloWorld unit tests', () => {
+  const ctx = new TestExecutionContext()
+
+  it('returns greeting', () => {
+    const contract = ctx.contract.create(HelloWorld)
+
+    const result = contract.sayHello('Sally', 'Jones')
+
+    expect(result).toBe('Hello Sally Jones')
+  })
+
+  it('returns bananas', () => {
+    const contract = ctx.contract.create(HelloWorld)
+
+    const result = contract.sayBananas()
+
+    expect(result).toBe('Bananas')
+  })
+})
+```
+
+## Testing with State
+
+```typescript
+import { TestExecutionContext } from '@algorandfoundation/algorand-typescript-testing'
+import { Uint64 } from '@algorandfoundation/algorand-typescript'
+import { describe, expect, it, afterEach } from 'vitest'
+import CounterContract from './contract.algo'
+
+describe('Counter unit tests', () => {
+  const ctx = new TestExecutionContext()
+
+  afterEach(() => {
+    ctx.reset()
+  })
+
+  it('increments counter', () => {
+    const contract = ctx.contract.create(CounterContract)
+
+    contract.increment()
+    contract.increment()
+
+    // Access state directly on contract instance
+    expect(contract.counter.value).toBe(Uint64(2))
+  })
+})
+```
+
+## Testing with Multiple Accounts
+
+```typescript
+it('supports multiple accounts', () => {
+  const contract = ctx.contract.create(MyContract)
+
+  // Create test accounts
+  const account1 = ctx.any.account()
+  const account2 = ctx.any.account()
+
+  // Change sender for subsequent calls
+  ctx.txn.sender = account1
+  contract.doSomething()
+
+  ctx.txn.sender = account2
+  contract.doSomethingElse()
+})
+```
+
+## Testing Boxes
+
+```typescript
+it('sets box value', () => {
+  const contract = ctx.contract.create(BoxContract)
+  const key = Bytes('myKey')
+  const value = Bytes('myValue')
+
+  contract.setBox(key, value)
+
+  // Access box via ledger context
+  const storedValue = ctx.ledger.getBox(contract, key)
+  expect(storedValue).toEqual(value)
+})
+```
+
+## Documentation
+
+- [TypeScript Unit Testing Guide](https://dev.algorand.co/algokit/unit-testing/typescript/overview)
+- [TestExecutionContext API](https://dev.algorand.co/algokit/unit-testing/typescript/concepts)
+- [State Management in Tests](https://dev.algorand.co/algokit/unit-testing/typescript/state-management)

package/skills/algorand-typescript/references/test-smart-contracts.md

@@ -0,0 +1,127 @@
+
+# Testing Smart Contracts
+
+Write integration tests for Algorand smart contracts using the `algorandFixture` and generated typed clients.
+
+## Default: Integration Tests (E2E)
+
+**Always write integration tests unless the user explicitly requests unit tests.** Integration tests run against LocalNet and test real contract behavior.
+
+**Test Framework**: Both Vitest (default) and Jest are supported. The examples below use Vitest syntax, but Jest equivalents work identically.
+
+### File naming
+
+- Integration tests: `contract.algo.e2e.spec.ts`
+- Unit tests (only if requested): `contract.algo.spec.ts`
+
+### Canonical Example
+
+Study and adapt from: [devportal-code-examples/contracts/HelloWorld](https://github.com/algorandfoundation/devportal-code-examples/tree/main/projects/typescript-examples/contracts/HelloWorld)
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+import { algorandFixture } from '@algorandfoundation/algokit-utils/testing'
+import { Address } from 'algosdk'
+import { beforeAll, beforeEach, describe, expect, test } from 'vitest'
+import { MyContractFactory } from '../artifacts/clients/MyContract/MyContractClient'
+
+describe('MyContract', () => {
+  const localnet = algorandFixture()
+
+  beforeAll(() => {
+    Config.configure({ debug: true })
+  })
+  // 10-second timeout: LocalNet needs time to process transactions and confirm blocks
+  beforeEach(localnet.newScope, 10_000)
+
+  const deploy = async (account: Address) => {
+    const factory = localnet.algorand.client.getTypedAppFactory(MyContractFactory, {
+      defaultSender: account,
+    })
+    const { appClient } = await factory.deploy({
+      onUpdate: 'append',
+      onSchemaBreak: 'append',
+      suppressLog: true,
+    })
+    return { client: appClient }
+  }
+
+  test('should call method and verify result', async () => {
+    const { testAccount } = localnet.context
+    const { client } = await deploy(testAccount)
+
+    const result = await client.send.myMethod({ args: { value: 42n } })
+    expect(result.return).toBe(42n)
+  })
+})
+```
+
+## How to proceed
+
+1. **Locate the generated client** in `artifacts/clients/<ContractName>/<ContractName>Client.ts`
+2. **Import the Factory** (e.g., `MyContractFactory`) - NOT the Client directly
+3. **Use the deploy helper pattern** shown above
+4. **Call methods via `client.send.methodName()`** or `client.newGroup().methodName().send()`
+
+## Critical Rules
+
+| Rule | Details |
+|------|---------|
+| **Use newGroup() for chaining** | `client.newGroup().method1().method2().send()` |
+| **Struct returns are tuples** | `const [id, name] = result.return as [bigint, string]` |
+| **Fund app for BoxMap** | Send payment to `client.appAddress` before box operations |
+| **Opt-in before local state** | `await client.newGroup().optIn.optInToApplication().send()` |
+
+## Common Patterns
+
+### Fund contract for box storage
+
+```typescript
+await localnet.algorand.send.payment({
+  amount: (1).algo(),
+  sender: testAccount,
+  receiver: client.appAddress,
+})
+```
+
+### Multiple users on same contract
+
+```typescript
+// Create and fund second user
+const user2 = localnet.algorand.account.random()
+await localnet.algorand.send.payment({
+  amount: (5).algo(),
+  sender: testAccount,
+  receiver: user2.addr,
+})
+
+// Get client for same app with different sender
+const client2 = factory.getAppClientById({
+  appId: client.appId,
+  defaultSender: user2.addr,
+})
+```
+
+### Box references
+
+```typescript
+import { ABIUintType } from 'algosdk'
+
+function createBoxReference(appId: bigint, prefix: string, key: bigint) {
+  const uint64Type = new ABIUintType(64)
+  const encodedKey = uint64Type.encode(key)
+  const boxName = new Uint8Array([...new TextEncoder().encode(prefix), ...encodedKey])
+  return { appId, name: boxName }
+}
+
+await client.send.setBoxMap({
+  args: { key: 1n, value: 'hello' },
+  boxReferences: [createBoxReference(client.appId, 'boxMap', 1n)],
+})
+```
+
+## References
+
+- [Canonical Examples](./test-smart-contracts-examples.md) - Complete patterns from algorandfoundation repos
+- [Unit Testing Guide](./test-smart-contracts-unit-tests.md) - Only use if user requests unit tests
+- [devportal-code-examples](https://github.com/algorandfoundation/devportal-code-examples/tree/main/projects/typescript-examples/contracts)