@goplausible/openclaw-algorand-plugin 0.5.0

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

@@ -0,0 +1,74 @@
+# Building Smart Contracts (TypeScript)
+
+Create Algorand smart contracts using Algorand TypeScript (PuyaTs) -- a statically-typed TypeScript subset compiled to TEAL bytecode by the Puya compiler.
+
+## Core Workflow
+
+1. **Search documentation** for concepts and best practices
+2. **Retrieve canonical TypeScript examples** from priority repositories
+3. **Generate code** following Algorand TypeScript syntax rules
+4. **Include integration tests** using generated clients
+5. **Build and test** with AlgoKit commands
+
+## TypeScript Repository Priorities
+
+When retrieving examples, search these repositories in order:
+
+1. **`algorandfoundation/devportal-code-examples`**
+   - Path: `projects/typescript-examples/contracts/`
+   - Best source for common patterns (BoxStorage, state management, etc.)
+   - Always include corresponding test files
+
+2. **`algorandfoundation/puya-ts`**
+   - Path: `examples/`
+   - Examples: `hello_world_arc4/`, `voting/`, `amm/`
+   - Best for compiler-level patterns and advanced features
+
+3. **`algorandfoundation/algokit-typescript-template`**
+   - Project scaffolding and structure reference
+   - Integration test patterns
+
+## TypeScript-Specific Patterns
+
+### File Extension
+All Algorand TypeScript contract files must use the `.algo.ts` extension:
+```
+contracts/MyContract.algo.ts
+```
+
+### Clone Pattern
+When working with mutable ARC-4 types, use `clone()` to avoid aliasing issues:
+```typescript
+const copy = original.clone()
+```
+
+### Key Syntax Rules
+
+- Contracts extend `Contract` class from `@algorandfoundation/algorand-typescript`
+- Use `@abimethod()` decorator for ABI-callable methods
+- Use `GlobalState<T>` and `LocalState<T>` for on-chain storage
+- Use `itxn` namespace for inner transactions
+- Always set `fee: 0` on inner transactions (fee pooling)
+
+For full TypeScript syntax rules, see the `algorand-typescript-syntax` topic and its detailed references.
+
+## Build and Test
+
+```bash
+algokit project run build   # Compile contracts
+algokit project run test    # Run tests
+```
+
+## Important Rules
+
+- **NEVER use PyTEAL or Beaker** -- these are legacy
+- **NEVER write raw TEAL** -- always use Algorand TypeScript
+- **NEVER import external libraries** into contract code
+- **Always search docs first** before writing code
+- **Always retrieve TypeScript examples** from priority repositories
+
+## References
+
+- [TypeScript Repository and Pattern Reference](./build-smart-contracts-reference.md)
+- [Algorand TypeScript Syntax](./algorand-typescript-syntax.md)
+- [TypeScript Syntax Reference](./algorand-typescript-syntax-reference.md)

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

@@ -0,0 +1,237 @@
+# Calling Smart Contracts Reference
+
+CLI commands and TypeScript client patterns for contract interaction.
+
+## CLI Commands
+
+### Build Contract
+
+```bash
+algokit project run build
+```
+
+Compiles contracts and generates:
+- ARC-56 app spec (`*.arc56.json`)
+- TypeScript client (`client.ts`)
+
+### Deploy Contract
+
+```bash
+# To localnet
+algokit project deploy localnet
+
+# To testnet (requires funded account)
+algokit project deploy testnet
+
+# To mainnet
+algokit project deploy mainnet
+```
+
+### Localnet Management
+
+```bash
+# Start localnet
+algokit localnet start
+
+# Check status
+algokit localnet status
+
+# Reset (clears all data)
+algokit localnet reset
+
+# Stop
+algokit localnet stop
+```
+
+### Run Custom Scripts
+
+```bash
+# Run a TypeScript script
+npx tsx scripts/my-script.ts
+```
+
+---
+
+## TypeScript Client Patterns
+
+### Initialize AlgorandClient
+
+```typescript
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+
+// From environment (reads ALGORAND_* env vars)
+const algorand = AlgorandClient.fromEnvironment()
+
+// Explicit localnet
+const algorand = AlgorandClient.defaultLocalNet()
+
+// Explicit testnet
+const algorand = AlgorandClient.testNet()
+
+// Explicit mainnet
+const algorand = AlgorandClient.mainNet()
+```
+
+### Get Account
+
+```typescript
+// From environment variable (e.g., DEPLOYER_MNEMONIC)
+const account = await algorand.account.fromEnvironment('DEPLOYER')
+
+// From mnemonic directly
+const account = await algorand.account.fromMnemonic('word1 word2 ...')
+
+// Localnet dispenser (auto-funded)
+const dispenser = await algorand.account.localNetDispenser()
+```
+
+### Create Typed Client
+
+```typescript
+import { MyContractClient } from './artifacts/MyContract/client'
+
+// By App ID (for existing deployment)
+const client = algorand.client.getTypedAppClientById(MyContractClient, {
+  appId: BigInt(1234),
+  sender: account,
+})
+
+// By creator (finds latest deployment by creator address)
+const client = await algorand.client.getTypedAppClientByCreatorAndName(MyContractClient, {
+  creatorAddress: account.addr,
+  sender: account,
+})
+```
+
+### Call Methods
+
+```typescript
+// No arguments, no return
+await client.send.myMethod({})
+
+// With arguments
+await client.send.setValue({ args: { value: 42n } })
+
+// With payment
+await client.send.deposit({
+  args: { amount: 1_000_000n },
+  extraFee: AlgoAmount.MicroAlgos(1000),
+})
+
+// Get return value
+const result = await client.send.getValue({})
+console.log(result.return) // typed return value
+
+// With version parameters (for versioned contracts)
+await client.send.myMethod({
+  args: { value: 42n },
+  appVersion: '1.0.0',      // Optional: specify expected app version
+  rejectVersion: '0.9.0',   // Optional: reject if app is this version
+})
+```
+
+### Read State
+
+```typescript
+// Global state - all keys
+const globalState = await client.state.global.getAll()
+
+// Global state - specific typed key
+const count = await client.state.global.count()
+
+// Local state for an address
+const localState = await client.state.local(address).getAll()
+
+// Box storage
+const boxValue = await client.state.box.myBox()
+```
+
+### Opt-In / Close-Out
+
+```typescript
+// Opt-in with ABI method
+await client.send.optIn.optIn({})
+
+// Bare opt-in (no method call)
+await client.send.optIn.bare({})
+
+// Close-out with ABI method
+await client.send.closeOut.closeOut({})
+
+// Bare close-out
+await client.send.closeOut.bare({})
+```
+
+### Delete Application
+
+```typescript
+// With ABI method
+await client.send.delete.deleteApplication({})
+
+// Bare delete
+await client.send.delete.bare({})
+```
+
+---
+
+## deploy-config.ts Pattern
+
+The standard deployment configuration file:
+
+```typescript
+// smart_contracts/deploy-config.ts
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+import { MyContractClient } from './artifacts/MyContract/client'
+
+export async function deploy() {
+  const algorand = AlgorandClient.fromEnvironment()
+  const deployer = await algorand.account.fromEnvironment('DEPLOYER')
+
+  const client = await algorand.client.getTypedAppClientByCreatorAndName(
+    MyContractClient,
+    {
+      creatorAddress: deployer.addr,
+      sender: deployer,
+    }
+  )
+
+  // Deploy or get existing
+  const app = await client.deploy({
+    onUpdate: 'update',
+    onSchemaBreak: 'replace',
+  })
+
+  console.log(`App ID: ${app.appId}`)
+  return app
+}
+```
+
+---
+
+## Error Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| "logic eval error" | Contract rejected call | Check method args, contract logic |
+| "below min" | Insufficient funds | Fund the sender account |
+| "not opted in" | Account hasn't opted in | Call opt-in first |
+| "app does not exist" | Wrong App ID | Verify App ID from deployment |
+| "network unreachable" | Localnet not running | `algokit localnet start` |
+| "Cannot find module" | Client not generated | `algokit project run build` |
+
+---
+
+## Environment Variables
+
+```bash
+# Network selection
+ALGORAND_NETWORK=localnet  # or testnet, mainnet
+
+# Account mnemonic (for testnet/mainnet)
+DEPLOYER_MNEMONIC="word1 word2 word3 ..."
+
+# Algod connection (usually auto-configured)
+ALGOD_SERVER=http://localhost
+ALGOD_PORT=4001
+ALGOD_TOKEN=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+```

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

@@ -0,0 +1,183 @@
+
+# Calling Smart Contracts
+
+Deploy and interact with Algorand smart contracts using AlgoKit CLI and the generated TypeScript client.
+
+## Overview / Core Workflow
+
+1. Build the contract: `algokit project run build`
+2. Deploy using CLI: `algokit project deploy localnet`
+3. Write TypeScript scripts using the generated client
+4. Run scripts: `npx tsx scripts/my-script.ts`
+
+## How to proceed
+
+### 1. Build the Contract
+
+```bash
+algokit project run build
+```
+
+This compiles your contract and generates:
+- `artifacts/<ContractName>/<ContractName>.arc56.json` — ARC-56 app spec
+- `artifacts/<ContractName>/client.ts` — Generated TypeScript client
+
+### 2. Deploy to Localnet
+
+```bash
+# Start localnet if not running
+algokit localnet start
+
+# Deploy (runs deploy-config.ts)
+algokit project deploy localnet
+```
+
+The deployment script (`smart_contracts/deploy-config.ts`) handles:
+- Idempotent deployment (safe to re-run)
+- App ID tracking
+- Initial state setup
+
+Note the App ID from the deployment output.
+
+### 3. Interact Using Generated Client
+
+Create scripts in your project to call contract methods. Example structure:
+
+```typescript
+// scripts/call-contract.ts
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+import { CounterClient } from '../smart_contracts/artifacts/Counter/client'
+
+async function main() {
+  // Connect to localnet
+  const algorand = AlgorandClient.fromEnvironment()
+
+  // Get the default account (localnet dispenser)
+  const deployer = await algorand.account.fromEnvironment('DEPLOYER')
+
+  // Create client for deployed app
+  const client = algorand.client.getTypedAppClientById(CounterClient, {
+    appId: BigInt(1234), // Replace with actual App ID
+    sender: deployer,
+  })
+
+  // Call a method
+  const result = await client.send.increment({})
+  console.log('New count:', result.return)
+
+  // Read global state
+  const state = await client.state.global.getAll()
+  console.log('Global state:', state)
+}
+
+main().catch(console.error)
+```
+
+Run with:
+```bash
+npx tsx scripts/call-contract.ts
+```
+
+### 4. Common Operations
+
+#### Call a Method
+
+```typescript
+// No arguments
+const result = await client.send.increment({})
+
+// With arguments
+const result = await client.send.setValue({ args: { value: 42n } })
+
+// Access return value
+console.log('Return:', result.return)
+```
+
+#### Read Global State
+
+```typescript
+// Get all global state
+const state = await client.state.global.getAll()
+
+// Get specific key (if typed in contract)
+const count = await client.state.global.count()
+```
+
+#### Read Local State
+
+```typescript
+// Get local state for an address
+const localState = await client.state.local(address).getAll()
+```
+
+#### Opt-In to Application
+
+```typescript
+// If contract has an opt_in method
+await client.send.optIn.optIn({})
+
+// Or use bare opt-in
+await client.send.optIn.bare({})
+```
+
+#### Read Box Storage
+
+```typescript
+// If contract uses boxes
+const boxValue = await client.state.box.myBox()
+```
+
+#### Bulk Opt-In/Opt-Out
+
+For batch operations across multiple assets:
+
+```typescript
+// Bulk opt-in to multiple assets
+const group = algorand.newGroup()
+for (const assetId of assetIds) {
+  group.addAssetOptIn({ sender: account.addr, assetId })
+}
+await group.send()
+
+// Bulk opt-out from multiple assets
+const closeGroup = algorand.newGroup()
+for (const assetId of assetIds) {
+  closeGroup.addAssetOptOut({ sender: account.addr, assetId, creator: creatorAddr })
+}
+await closeGroup.send()
+```
+
+## Important Rules / Guidelines
+
+- **Always build before deploying**: Run `algokit project run build` to generate fresh artifacts
+- **Use generated clients**: They provide type safety and handle ABI encoding
+- **Check App ID**: Get it from deployment output, don't hardcode across environments
+- **Use environment variables**: Store sensitive data like mnemonics in `.env`
+- **Localnet accounts**: Use `algorand.account.fromEnvironment('DEPLOYER')` for localnet
+
+## Common Variations / Edge Cases
+
+| Scenario | Approach |
+|----------|----------|
+| Deploy to testnet | `algokit project deploy testnet` (requires funded account) |
+| Custom sender | Create account with `algorand.account.fromMnemonic()` |
+| Multiple contracts | Create separate client instances for each |
+| State not found | Ensure app is deployed and App ID is correct |
+| Method not found | Rebuild contract and regenerate client |
+
+## Environment Setup
+
+For non-localnet deployments, set environment variables:
+
+```bash
+# .env file
+ALGORAND_NETWORK=testnet
+DEPLOYER_MNEMONIC="your twenty four word mnemonic phrase here"
+```
+
+## References / Further Reading
+
+- [CLI Commands Reference](./call-smart-contracts-reference.md)
+- [AlgoKit Utils Documentation](https://dev.algorand.co/algokit/utils/typescript/)
+- [ARC-56 App Spec Standard](https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0056.md)
+- [Testing Contracts](./test-smart-contracts.md)

package/skills/algorand-typescript/references/create-project-reference.md

@@ -0,0 +1,53 @@
+# AlgoKit Init CLI Reference (TypeScript)
+
+## TypeScript Presets
+
+| Preset       | Description                  |
+| ------------ | ---------------------------- |
+| `Starter`    | Simple starting point        |
+| `Production` | Tests, CI/CD, linting, audit |
+
+## TypeScript Templates
+
+| Template     | Use Case                                      |
+| ------------ | --------------------------------------------- |
+| `typescript` | Smart contracts (Algorand TypeScript/PuyaTs)  |
+| `react`      | Frontend dApp with wallet integration         |
+| `fullstack`  | Smart contracts + React frontend combined     |
+
+## Command Patterns
+
+```bash
+# TypeScript (Production preset)
+algokit init -n <name> -t typescript --answer preset_name production --answer author_name "<author>" --defaults
+
+# TypeScript (Starter preset)
+algokit init -n <name> -t typescript --answer author_name "<author>" --defaults
+
+# React frontend
+algokit init -n <name> -t react --defaults
+
+# Fullstack (contracts + React frontend)
+algokit init -n <name> -t fullstack --defaults
+
+# Skip git and bootstrap
+algokit init -n <name> -t typescript --no-git --no-bootstrap --defaults
+```
+
+## Options
+
+| Flag                         | Description                                      |
+| ---------------------------- | ------------------------------------------------ |
+| `-n, --name <name>`          | Project directory name (required)                |
+| `-t, --template <name>`      | Template name (`typescript`, `react`, `fullstack`)|
+| `--answer "<key>" "<value>"` | Answer template prompts                          |
+| `--defaults`                 | Accept all defaults                              |
+| `--no-git`                   | Skip git initialization                          |
+| `--no-bootstrap`             | Skip dependency installation                     |
+| `--workspace`                | Create within workspace structure (default)      |
+| `--no-workspace`             | Create standalone project                        |
+
+## Full Reference
+
+- [AlgoKit Init Command](https://dev.algorand.co/reference/algokit-cli/#init)
+- [AlgoKit Templates](https://dev.algorand.co/algokit/official-algokit-templates/)

package/skills/algorand-typescript/references/create-project.md

@@ -0,0 +1,86 @@
+# AlgoKit Project Initialization (TypeScript)
+
+Create new Algorand TypeScript projects using AlgoKit's official templates.
+
+## Overview / Core Workflow
+
+1. Confirm project details with user (name, preset, customizations)
+2. Run `algokit init` with the TypeScript template
+3. Handle any initialization errors
+4. Provide next steps for building/testing
+
+## How to Proceed
+
+1. **Confirm project details with user:**
+   - Project name (directory name)
+   - Preset choice (Production or Starter)
+   - Any customizations (`--no-git`, `--no-bootstrap`, author name)
+
+2. **Run initialization command:**
+
+   **TypeScript (Production Preset):**
+
+   ```bash
+   algokit init -n <project-name> -t typescript --answer preset_name production --answer author_name "<name>" --defaults
+   ```
+
+   **TypeScript (Starter Preset):**
+
+   ```bash
+   algokit init -n <project-name> -t typescript --answer author_name "<name>" --defaults
+   ```
+
+3. **Handle errors:**
+   - Check if project directory already exists
+   - Verify AlgoKit is installed: `algokit --version`
+   - Ensure target directory is writable
+
+4. **Provide next steps:**
+   - `cd <project-name>`
+   - `algokit project run build` -- Compile contracts
+   - `algokit project run test` -- Run test suite
+   - `algokit localnet start` -- Start local network (if deploying)
+   - `algokit project run deploy` -- Deploy contracts to local network
+
+## TypeScript Templates
+
+| Template     | Use Case                                      |
+| ------------ | --------------------------------------------- |
+| `typescript` | Smart contracts (Algorand TypeScript/PuyaTs)  |
+| `react`      | Frontend dApp with wallet integration         |
+| `fullstack`  | Smart contracts + React frontend combined     |
+
+### React Frontend
+
+```bash
+algokit init -n <project-name> -t react --defaults
+```
+
+### Fullstack (Contracts + React Frontend)
+
+```bash
+algokit init -n <project-name> -t fullstack --defaults
+```
+
+## TypeScript-Specific Customizations
+
+| Customization | Command |
+|---------------|---------|
+| Set author name | `--answer author_name "Your Name"` |
+| Production preset | `--answer preset_name production` |
+| Starter preset | Omit `preset_name` (default) |
+| Skip git init | `--no-git` |
+| Skip dependency install | `--no-bootstrap` |
+
+## Important Rules / Guidelines
+
+- **Always confirm with user before executing** -- Never run `algokit init` without explicit confirmation
+- **Use production preset** -- For any serious project because it includes testing framework and deployment scripts
+- **Include author name** -- Pass `--answer author_name "<name>"` for attribution
+- **Use `--defaults`** -- Accepts all other default values for non-interactive mode
+
+## References / Further Reading
+
+- [CLI Reference](./create-project-reference.md)
+- [AlgoKit CLI Init Documentation](https://dev.algorand.co/algokit/cli/init/)
+- [AlgoKit CLI Init Reference](https://dev.algorand.co/reference/algokit-cli#init)