openclaw-algorand-plugin 0.5.0

package/skills/algorand-typescript/references/deploy-react-frontend-reference.md

@@ -0,0 +1,412 @@
+# React Frontend Reference
+
+Detailed API reference for building Algorand React frontends.
+
+## Dependencies
+
+Core packages:
+```json
+{
+  "dependencies": {
+    "@algorandfoundation/algokit-utils": "^9.0.0",
+    "@txnlab/use-wallet-react": "^4.0.0",
+    "algosdk": "^3.0.0",
+    "react": "^18.2.0"
+  }
+}
+```
+
+Wallet peer dependencies (install only for wallets you're using):
+
+| Wallet | Package |
+|--------|---------|
+| Pera | `@perawallet/connect` |
+| Defly | `@blockshake/defly-connect` |
+| Kibisis | `@agoralabs-sh/avm-web-provider` |
+| Lute | `lute-connect` |
+
+Example for Pera + Defly:
+```bash
+npm install @perawallet/connect @blockshake/defly-connect
+```
+
+## WalletManager Configuration
+
+Create a `WalletManager` instance to configure available wallets:
+
+```tsx
+import { NetworkId, WalletId, WalletManager } from '@txnlab/use-wallet-react'
+
+const walletManager = new WalletManager({
+  wallets: WalletId[] | WalletConfig[],
+  defaultNetwork: NetworkId | string,
+  networks?: NetworkConfig,
+  options?: ManagerOptions,
+})
+```
+
+### Wallet IDs
+
+| Wallet ID | Type | Notes |
+|-----------|------|-------|
+| `WalletId.PERA` | Mobile/Browser | Most popular Algorand wallet |
+| `WalletId.DEFLY` | Mobile/Browser | Feature-rich wallet |
+| `WalletId.EXODUS` | Desktop/Mobile | Multi-chain wallet |
+| `WalletId.KIBISIS` | Browser Extension | AVM standard |
+| `WalletId.LUTE` | Browser | Community wallet |
+| `WalletId.KMD` | LocalNet only | For local development |
+
+### Network IDs
+
+```tsx
+import { NetworkId } from '@txnlab/use-wallet-react'
+
+NetworkId.MAINNET   // 'mainnet'
+NetworkId.TESTNET   // 'testnet'
+NetworkId.BETANET   // 'betanet'
+```
+
+### Basic Configuration
+
+```tsx
+// TestNet/MainNet with popular wallets
+const walletManager = new WalletManager({
+  wallets: [WalletId.PERA, WalletId.DEFLY, WalletId.EXODUS],
+  defaultNetwork: NetworkId.TESTNET,
+})
+```
+
+### Custom Network Configuration
+
+```tsx
+const walletManager = new WalletManager({
+  wallets: [WalletId.PERA, WalletId.DEFLY],
+  defaultNetwork: NetworkId.TESTNET,
+  networks: {
+    [NetworkId.TESTNET]: {
+      algod: {
+        baseServer: 'https://testnet-api.algonode.cloud',
+        port: '',
+        token: '',
+      },
+    },
+  },
+})
+```
+
+### LocalNet Configuration (Development)
+
+```tsx
+const walletManager = new WalletManager({
+  wallets: [
+    {
+      id: WalletId.KMD,
+      options: {
+        baseServer: 'http://localhost',
+        port: '4002',
+        token: 'a]'.repeat(64),
+        wallet: 'unencrypted-default-wallet',
+      },
+    },
+  ],
+  defaultNetwork: 'localnet',
+  networks: {
+    localnet: {
+      algod: {
+        baseServer: 'http://localhost',
+        port: '4001',
+        token: 'a'.repeat(64),
+      },
+    },
+  },
+})
+```
+
+## useWallet() Hook
+
+The primary hook for wallet interactions:
+
+```tsx
+import { useWallet } from '@txnlab/use-wallet-react'
+
+const {
+  // Wallet state
+  wallets,              // Wallet[] - all available wallets
+  isReady,              // boolean - manager initialized
+
+  // Active wallet info
+  activeWallet,         // Wallet | null - current wallet
+  activeAddress,        // string | null - current address
+  activeWalletAccounts, // WalletAccount[] - accounts in active wallet
+
+  // Signing
+  transactionSigner,    // TransactionSigner - for signing txns
+  signTransactions,     // (txns, indexes?) => Promise<Uint8Array[]>
+
+  // Clients
+  algodClient,          // Algodv2 - algod client instance
+} = useWallet()
+```
+
+### Wallet Object
+
+Each wallet in the `wallets` array has:
+
+```tsx
+interface Wallet {
+  id: WalletId
+  metadata: { name: string; icon: string }
+  accounts: WalletAccount[]
+  activeAccount: WalletAccount | null
+  isConnected: boolean
+  isActive: boolean
+
+  // Methods
+  connect: () => Promise<WalletAccount[]>
+  disconnect: () => Promise<void>
+  setActive: () => void
+  setActiveAccount: (address: string) => void
+}
+```
+
+### WalletAccount Object
+
+```tsx
+interface WalletAccount {
+  name: string
+  address: string
+}
+```
+
+## AlgorandClient Signer Methods
+
+Register wallet signers with `AlgorandClient`:
+
+```tsx
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+
+const algorand = AlgorandClient.testNet()
+
+// Register signer for specific address
+algorand.setSigner(address: string, signer: TransactionSigner)
+
+// Register signer from account object
+algorand.setSignerFromAccount(account: { addr: string; signer: TransactionSigner })
+
+// Set default signer for all transactions
+algorand.setDefaultSigner(signer: TransactionSigner)
+```
+
+### Signer Resolution Order
+
+When sending transactions, AlgorandClient resolves signers in this order:
+
+1. Explicit `signer` parameter in the method call
+2. Registered signer for the sender address (via `setSigner()`)
+3. Default signer (via `setDefaultSigner()`)
+
+## AlgorandClient Factory Methods
+
+```tsx
+// Network presets
+AlgorandClient.mainNet()     // MainNet via AlgoNode
+AlgorandClient.testNet()     // TestNet via AlgoNode
+AlgorandClient.defaultLocalNet()  // LocalNet defaults
+
+// From configuration
+AlgorandClient.fromConfig({
+  algodConfig: { server: '...', port: '...', token: '...' },
+})
+
+// From environment variables
+AlgorandClient.fromEnvironment()
+```
+
+## Typed App Client Methods
+
+### Get Client by App ID
+
+```tsx
+const appClient = algorand.client.getTypedAppClientById(
+  MyContractClient,  // Generated client class
+  {
+    appId: 12345n,                    // Required: App ID
+    defaultSender: activeAddress,     // Optional: default sender
+    defaultSigner: transactionSigner, // Optional: explicit signer
+  }
+)
+```
+
+### Get Client by Creator and Name
+
+```tsx
+const appClient = await algorand.client.getTypedAppClientByCreatorAndName(
+  MyContractClient,
+  {
+    creatorAddress: 'ABC123...',
+    appName: 'MyContract',         // Optional: defaults to spec name
+    defaultSender: activeAddress,
+  }
+)
+```
+
+### Get Client by Network (ARC-56)
+
+For contracts with network-specific App IDs in their spec:
+
+```tsx
+const appClient = await algorand.client.getTypedAppClientByNetwork(
+  MyContractClient,
+  {
+    defaultSender: activeAddress,
+  }
+)
+```
+
+## Typed App Factory
+
+Use factories to deploy new contracts or manage multiple instances:
+
+```tsx
+import { MyContractFactory } from './contracts/MyContractClient'
+
+// Create factory
+const factory = new MyContractFactory({
+  algorand,
+  defaultSender: activeAddress,
+})
+
+// Deploy new instance
+const { appClient, result } = await factory.deploy({
+  onSchemaBreak: 'append',  // 'replace' | 'append' | 'fail'
+  onUpdate: 'append',       // 'replace' | 'append' | 'fail'
+})
+
+// Get client for existing app by ID
+const existingClient = factory.getAppClientById({ appId: 12345n })
+
+// Get client by creator and name
+const namedClient = await factory.getAppClientByCreatorAndName({
+  creatorAddress: 'ABC123...',
+  appName: 'MyContract',
+})
+```
+
+## Calling Contract Methods
+
+### Send (Execute Transaction)
+
+```tsx
+// Single method call
+const result = await appClient.send.methodName({
+  args: { param1: 'value', param2: 42n },
+})
+
+console.log(result.return)     // Return value
+console.log(result.txIds)      // Transaction IDs
+console.log(result.transaction) // Transaction object
+```
+
+### Simulate (Dry Run)
+
+```tsx
+// Test without submitting
+const simResult = await appClient.newGroup()
+  .methodName({ args: { param1: 'value' } })
+  .simulate()
+
+console.log(simResult.returns[0]) // Simulated return value
+```
+
+### Chained Calls (Atomic Group)
+
+```tsx
+const result = await appClient.newGroup()
+  .method1({ args: { ... } })
+  .method2({ args: { ... } })
+  .send()
+```
+
+## App Client Properties
+
+```tsx
+appClient.appId        // bigint - Application ID
+appClient.appAddress   // string - Application account address
+appClient.appName      // string - Application name
+appClient.appSpec      // Arc56Contract - ARC-56 spec
+```
+
+## Payment Transactions
+
+Send ALGO payments using the wallet signer:
+
+```tsx
+import { algo } from '@algorandfoundation/algokit-utils'
+
+const result = await algorand.send.payment({
+  sender: activeAddress,
+  receiver: 'RECIPIENTADDRESS...',
+  amount: algo(1),  // 1 ALGO
+  signer: transactionSigner,
+})
+```
+
+## Error Handling Pattern
+
+```tsx
+const callContract = async () => {
+  if (!activeAddress || !transactionSigner) {
+    throw new Error('Wallet not connected')
+  }
+
+  try {
+    const algorand = AlgorandClient.testNet()
+    algorand.setSigner(activeAddress, transactionSigner)
+
+    const appClient = algorand.client.getTypedAppClientById(MyContractClient, {
+      appId: APP_ID,
+      defaultSender: activeAddress,
+    })
+
+    const result = await appClient.send.myMethod({ args: { value: 42n } })
+    return result.return
+  } catch (error) {
+    if (error.message.includes('rejected')) {
+      // User cancelled in wallet
+      console.log('Transaction cancelled by user')
+    } else if (error.message.includes('below min')) {
+      // Insufficient funds
+      console.log('Insufficient balance')
+    } else {
+      // Other error
+      console.error('Transaction failed:', error)
+    }
+    throw error
+  }
+}
+```
+
+## Type Imports
+
+Common imports for TypeScript:
+
+```tsx
+// use-wallet
+import {
+  NetworkId,
+  WalletId,
+  WalletManager,
+  WalletProvider,
+  useWallet,
+} from '@txnlab/use-wallet-react'
+
+// AlgoKit Utils
+import {
+  AlgorandClient,
+  algo,
+  microAlgo,
+} from '@algorandfoundation/algokit-utils'
+
+// algosdk (rarely needed directly)
+import algosdk from 'algosdk'
+```

package/skills/algorand-typescript/references/deploy-react-frontend.md

@@ -0,0 +1,239 @@
+
+# Deploying React Frontends for Algorand
+
+Build React applications that connect to Algorand wallets and interact with smart contracts using typed clients.
+
+## Prerequisites
+
+Before using this skill, ensure:
+
+1. **Smart contract is deployed** with a known App ID
+2. **ARC-56/ARC-32 app spec exists** (e.g., `MyContract.arc56.json`)
+3. **React project is set up** (Vite, Next.js, or Create React App)
+
+## Core Workflow: The "Signer Handoff" Pattern
+
+The key insight is passing the wallet's transaction signer to AlgorandClient, which then provides it to typed app clients:
+
+```
+Wallet (use-wallet) → transactionSigner
+                              ↓
+                    AlgorandClient.setSigner()
+                              ↓
+                    Typed App Client (defaultSender)
+                              ↓
+                    Contract Method Calls (auto-signed)
+```
+
+## How to proceed
+
+### Step 1: Generate Typed Client
+
+Generate a TypeScript client from your contract's app spec:
+
+```bash
+algokit generate client path/to/MyContract.arc56.json --output src/contracts/MyContractClient.ts
+```
+
+This creates a typed client with full IntelliSense for your contract's methods.
+
+### Step 2: Install Dependencies
+
+Core packages:
+```bash
+npm install @algorandfoundation/algokit-utils @txnlab/use-wallet-react algosdk
+```
+
+Wallet peer dependencies (install only for wallets you're using):
+
+| Wallet | Package |
+|--------|---------|
+| Pera | `@perawallet/connect` |
+| Defly | `@blockshake/defly-connect` |
+| Kibisis | `@agoralabs-sh/avm-web-provider` |
+| Lute | `lute-connect` |
+
+Example for Pera + Defly:
+```bash
+npm install @perawallet/connect @blockshake/defly-connect
+```
+
+### Step 3: Set Up WalletProvider
+
+Wrap your app with `WalletProvider` at the root level:
+
+```tsx
+import { NetworkId, WalletId, WalletManager, WalletProvider } from '@txnlab/use-wallet-react'
+
+const walletManager = new WalletManager({
+  wallets: [WalletId.PERA, WalletId.DEFLY, WalletId.EXODUS],
+  defaultNetwork: NetworkId.TESTNET,
+})
+
+export default function App() {
+  return (
+    <WalletProvider manager={walletManager}>
+      <YourApp />
+    </WalletProvider>
+  )
+}
+```
+
+### Step 4: Create Wallet Connection UI
+
+Use the `useWallet()` hook to display available wallets:
+
+```tsx
+import { useWallet } from '@txnlab/use-wallet-react'
+
+function ConnectWallet() {
+  const { wallets, activeAddress } = useWallet()
+
+  if (activeAddress) {
+    return <p>Connected: {activeAddress}</p>
+  }
+
+  return (
+    <div>
+      {wallets.map((wallet) => (
+        <button key={wallet.id} onClick={() => wallet.connect()}>
+          Connect {wallet.metadata.name}
+        </button>
+      ))}
+    </div>
+  )
+}
+```
+
+### Step 5: Integrate Typed Client with Wallet Signer
+
+This is the critical integration step. Register the wallet's signer with AlgorandClient:
+
+```tsx
+import { useWallet } from '@txnlab/use-wallet-react'
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+import { MyContractClient } from './contracts/MyContractClient'
+
+function ContractInteraction() {
+  const { transactionSigner, activeAddress } = useWallet()
+
+  const callContract = async () => {
+    if (!activeAddress || !transactionSigner) {
+      alert('Please connect your wallet first')
+      return
+    }
+
+    // 1. Create AlgorandClient for the network
+    const algorand = AlgorandClient.testNet()
+
+    // 2. Register wallet signer with AlgorandClient
+    algorand.setSigner(activeAddress, transactionSigner)
+
+    // 3. Create typed client with wallet as default sender
+    const appClient = algorand.client.getTypedAppClientById(MyContractClient, {
+      appId: 12345n, // Your deployed App ID
+      defaultSender: activeAddress,
+    })
+
+    // 4. Call contract methods - signer is used automatically
+    const result = await appClient.send.myMethod({ args: { value: 42n } })
+    console.log('Result:', result.return)
+  }
+
+  return <button onClick={callContract}>Call Contract</button>
+}
+```
+
+### Step 6: Deploy New Contracts (Optional)
+
+If deploying from the frontend (less common), use the Factory pattern:
+
+```tsx
+import { MyContractFactory } from './contracts/MyContractClient'
+
+const factory = new MyContractFactory({
+  algorand,
+  defaultSender: activeAddress,
+})
+
+const { appClient } = await factory.deploy({
+  onSchemaBreak: 'append',
+  onUpdate: 'append',
+})
+```
+
+## Important Rules / Guidelines
+
+1. **Always call setSigner() before creating clients** - The signer must be registered with AlgorandClient first
+2. **Check for null activeAddress and transactionSigner** - They are null when no wallet is connected
+3. **Use TypeScript** - Typed clients provide full type safety and IntelliSense
+4. **Match networks** - Ensure AlgorandClient network matches WalletManager network
+5. **React only** - This skill covers React; other frameworks have different patterns
+
+## Getting the App Client
+
+Three ways to get a typed app client:
+
+| Method | Use Case |
+|--------|----------|
+| `getTypedAppClientById()` | Known App ID (most common for frontends) |
+| `getTypedAppClientByCreatorAndName()` | Resolve by creator address and app name |
+| `factory.deploy()` | Deploy new instance and get client |
+
+```tsx
+// By App ID (recommended for frontends)
+const appClient = algorand.client.getTypedAppClientById(MyContractClient, {
+  appId: 12345n,
+  defaultSender: activeAddress,
+})
+
+// By Creator and Name
+const appClient = await algorand.client.getTypedAppClientByCreatorAndName(
+  MyContractClient,
+  {
+    creatorAddress: 'CREATORADDRESS...',
+    appName: 'MyContract',
+  }
+)
+```
+
+## Common Errors / Troubleshooting
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| `activeAddress is null` | Wallet not connected | Check wallet connection before contract calls |
+| `transactionSigner is undefined` | No active wallet | Prompt user to connect wallet first |
+| `signer not found for address` | Signer not registered | Call `algorand.setSigner(activeAddress, transactionSigner)` |
+| `app does not exist` | Wrong App ID | Verify App ID matches deployed contract |
+| `Method not found` | Wrong method name or signature | Check typed client API; ensure args match ABI |
+| `Network mismatch` | Different networks | Ensure AlgorandClient and WalletManager use same network |
+| `User rejected transaction` | User cancelled in wallet | Handle rejection gracefully in UI |
+| `global is not defined` | algosdk references `global` in browser | Add to vite.config.ts: `define: { global: 'globalThis' }` |
+| TypeScript errors in generated client | Strict TS mode incompatibility | Set `verbatimModuleSyntax: false` in tsconfig.json |
+
+## Wallet Disconnect
+
+Handle wallet disconnection:
+
+```tsx
+function DisconnectButton() {
+  const { wallets } = useWallet()
+
+  const disconnect = async () => {
+    const activeWallet = wallets.find((w) => w.isActive)
+    if (activeWallet) {
+      await activeWallet.disconnect()
+    }
+  }
+
+  return <button onClick={disconnect}>Disconnect</button>
+}
+```
+
+## References / Further Reading
+
+- [REFERENCE.md](./deploy-react-frontend-reference.md) - Detailed API reference
+- [EXAMPLES.md](./deploy-react-frontend-examples.md) - Complete code examples
+- [use-wallet Documentation](https://txnlab.gitbook.io/use-wallet)
+- [AlgoKit Utils TypeScript](https://dev.algorand.co/algokit/utils/typescript/algorand-client/)
+- [Typed App Clients](https://dev.algorand.co/algokit/utils/typescript/typed-app-clients/)

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

@@ -0,0 +1,73 @@
+# ARC-32/56 Client Usage (TypeScript)
+
+This reference covers generating and using ARC-32/ARC-56 application specifications in TypeScript.
+
+## Table of Contents
+
+- [Generating App Specs](#generating-app-specs)
+- [TypeScript Client Usage](#typescript-client-usage)
+  - [Factory and Deployment](#factory-and-deployment)
+  - [Calling Methods](#calling-methods)
+  - [State Access](#state-access)
+- [Converting ARC-32 to ARC-56](#converting-arc-32-to-arc-56)
+
+## Generating App Specs
+
+```bash
+# Compile TypeScript contract - generates both .arc32.json and .arc56.json
+npx puya-ts contracts/my_contract.ts
+
+# Or via AlgoKit
+algokit project run build
+```
+
+Output files:
+- `MyContract.arc32.json` - Legacy app spec
+- `MyContract.arc56.json` - Modern app spec
+
+## TypeScript Client Usage
+
+### Factory and Deployment
+
+```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',
+})
+```
+
+### Calling Methods
+
+```typescript
+// Call methods with full type safety
+const result = await appClient.send.add({
+  args: { a: 10n, b: 20n }
+})
+console.log(result.return) // BigInt: 30n
+```
+
+### State Access
+
+```typescript
+// Read state with typed access
+const state = await appClient.state.global.getAll()
+console.log(state.counter) // Typed as bigint
+```
+
+## Converting ARC-32 to ARC-56
+
+AlgoKit Utils provides a conversion utility for migrating legacy ARC-32 specs:
+
+```typescript
+import { arc32ToArc56 } from '@algorandfoundation/algokit-utils'
+import arc32Spec from './MyContract.arc32.json'
+
+const arc56Spec = arc32ToArc56(arc32Spec)
+```