@goplausible/openclaw-algorand-plugin 0.5.0

package/skills/algorand-typescript/references/troubleshoot-errors-contract.md

@@ -0,0 +1,296 @@
+# Smart Contract Errors (TypeScript)
+
+TypeScript-focused fixes for common Algorand smart contract errors.
+
+## Table of Contents
+
+- [Logic Eval Errors](#logic-eval-errors)
+  - [Assert Failed](#assert-failed)
+  - [Opcode Budget Exceeded](#opcode-budget-exceeded)
+  - [Invalid Program](#invalid-program)
+  - [Stack Underflow](#stack-underflow)
+  - [Byte/Int Type Mismatch](#byteint-type-mismatch)
+- [ABI Errors](#abi-errors)
+  - [Method Not Found](#method-not-found)
+  - [ABI Encoding Error](#abi-encoding-error)
+  - [Return Value Decoding Error](#return-value-decoding-error)
+- [State Errors](#state-errors)
+  - [Global State Full](#global-state-full)
+  - [Local State Not Opted In](#local-state-not-opted-in)
+  - [Box Not Found](#box-not-found)
+  - [Box MBR Not Met](#box-mbr-not-met)
+- [Inner Transaction Errors](#inner-transaction-errors)
+- [Debugging Tips](#debugging-tips)
+
+## Logic Eval Errors
+
+### Assert Failed
+
+```
+logic eval error: assert failed pc=123
+```
+
+**Cause:** An `assert` statement evaluated to false.
+
+**Debug with source maps:**
+
+```typescript
+// Errors include source location automatically with AlgoKit Utils
+try {
+  await appClient.send.myMethod({ args: { value: 0 } })
+} catch (e) {
+  // Error includes: "assert failed at contracts/my_contract.py:45"
+  console.error(e)
+}
+```
+
+**Common causes:**
+- Input validation failed (e.g., `assert amount > 0`)
+- Authorization check failed (e.g., `assert Txn.sender == self.owner`)
+- State precondition not met (e.g., `assert self.is_initialized`)
+
+**Fix:** Check the assertion condition and ensure inputs satisfy it.
+
+### Opcode Budget Exceeded
+
+```
+logic eval error: dynamic cost budget exceeded
+```
+
+**Cause:** Contract exceeded the 700 opcode budget per app call.
+
+**Budget limits:**
+| Context | Budget |
+|---------|--------|
+| Single app call | 700 opcodes |
+| Max pooled (16 app calls) | 11,200 opcodes |
+| Logic signature | 20,000 opcodes |
+
+**Fix - Pool budget with extra app calls:**
+```typescript
+await algorand.newGroup()
+  .addAppCallMethodCall(actualCallParams)
+  .addAppCall({
+    sender: sender,
+    appId: appId,
+    onComplete: OnComplete.NoOp,
+    args: [new Uint8Array(Buffer.from('noop'))],  // Dummy call for budget
+  })
+  .send()
+```
+
+### Invalid Program
+
+```
+logic eval error: invalid program
+```
+
+**Cause:** The TEAL program is malformed or uses unsupported opcodes.
+
+**Common causes:**
+- Compiling for wrong AVM version
+- Using opcodes not supported on target network
+- Corrupted approval/clear program bytes
+
+**Fix:** Ensure compilation targets the correct AVM version.
+
+### Stack Underflow
+
+```
+logic eval error: stack underflow
+```
+
+**Cause:** Operation tried to pop from empty stack. Usually indicates a bug in low-level operations.
+
+### Byte/Int Type Mismatch
+
+```
+logic eval error: assert failed: wanted type uint64 but got []byte
+```
+
+**Cause:** Wrong type passed to an operation. Ensure correct types in contract code.
+
+## ABI Errors
+
+### Method Not Found
+
+```
+error: method "foo(uint64)void" not found
+```
+
+**Cause:** Calling a method that doesn't exist in the contract ABI.
+
+**Fix:**
+```typescript
+// 1. Regenerate typed client after contract changes
+// 2. Check method signature matches exactly
+// 3. Verify contract was deployed with latest code
+
+// Regenerate typed client
+// algokit generate client -a ./artifacts -o ./client.ts
+```
+
+### ABI Encoding Error
+
+```
+ABIEncodingError: value out of range for uint64
+```
+
+**Cause:** Value doesn't fit the ABI type. Check value ranges for the target type.
+
+### Return Value Decoding Error
+
+```
+error: could not decode return value
+```
+
+**Cause:** Method returned unexpected data format.
+
+**Common causes:**
+- Contract didn't log the return value properly
+- Wrong return type in client
+- Transaction failed before return
+
+**Fix:** Check contract method has correct return annotation.
+
+## State Errors
+
+### Global State Full
+
+```
+logic eval error: store global state: failed
+```
+
+**Cause:** Exceeded declared global state schema.
+
+**Fix:** Increase schema in contract deployment configuration.
+
+### Local State Not Opted In
+
+```
+logic eval error: application APPID not opted in
+```
+
+**Cause:** Account hasn't opted into the application.
+
+**Fix:**
+```typescript
+await algorand.send.appCall({
+  sender: userAddress,
+  appId: appId,
+  onComplete: OnComplete.OptIn,
+})
+```
+
+### Box Not Found
+
+```
+logic eval error: box not found
+```
+
+**Cause:** Accessing a box that doesn't exist. Create box before access or check existence in contract code.
+
+### Box MBR Not Met
+
+```
+logic eval error: box create with insufficient funds
+```
+
+**Cause:** App account lacks funds for box minimum balance requirement.
+
+**MBR formula:** `2500 + (400 * (key_length + value_length))` microAlgos per box
+
+**Fix:** Fund the app account:
+```typescript
+await algorand.send.payment({
+  sender: funder.address,
+  receiver: appClient.appAddress,
+  amount: algo(1),  // Cover box MBR
+})
+```
+
+## Inner Transaction Errors
+
+### Insufficient Balance for Inner Txn
+
+```
+logic eval error: insufficient balance
+```
+
+**Cause:** App account lacks funds for inner transaction amount.
+
+**Fix:** Fund the app account before calling methods with inner transactions:
+```typescript
+await algorand.send.payment({
+  sender: deployer.address,
+  receiver: appClient.appAddress,
+  amount: algo(5),
+})
+```
+
+### Inner Transaction Limit
+
+```
+logic eval error: too many inner transactions
+```
+
+**Cause:** Exceeded 256 inner transactions per group.
+
+**Fix:** Split operations across multiple outer transactions.
+
+### App Not Opted Into Asset
+
+```
+logic eval error: asset ASSET_ID not opted in
+```
+
+**Cause:** Contract account isn't opted into the asset. The contract must have an opt-in method that sends a 0-amount inner asset transfer.
+
+## Debugging Tips
+
+### Enable Debug Logging
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+Config.configure({ debug: true })
+```
+
+### Get Transaction Trace
+
+```typescript
+// Simulate to get execution trace
+const result = await algorand.newGroup()
+  .addAppCallMethodCall(params)
+  .simulate({ execTraceConfig: { enable: true } })
+
+console.log(result.simulateResponse.txnGroups[0].txnResults[0].execTrace)
+```
+
+### Simulate Before Sending
+
+```typescript
+const result = await algorand
+  .newGroup()
+  .addPayment({ sender, receiver, amount: algo(1) })
+  .simulate()
+
+if (result.simulateResponse.txnGroups[0].failureMessage) {
+  console.error('Would fail:', result.simulateResponse.txnGroups[0].failureMessage)
+}
+```
+
+### Check Program Counter Location
+
+When you see `pc=123`, use algokit to find the source:
+
+```bash
+algokit compile contracts/my_contract.py --output-sourcemap
+```
+
+Then map the PC to source using the generated `.map` file.
+
+## References
+
+- [Debugging Smart Contracts](https://dev.algorand.co/concepts/smart-contracts/debugging/)
+- [AVM Opcodes Reference](https://dev.algorand.co/reference/teal/opcodes/)
+- [Error Handling in AlgoKit Utils TS](https://dev.algorand.co/algokit/utils/typescript/debugging/)

package/skills/algorand-typescript/references/troubleshoot-errors-transaction.md

@@ -0,0 +1,438 @@
+# Transaction & Account Errors (TypeScript)
+
+TypeScript-focused fixes for common Algorand transaction and account errors.
+
+## Table of Contents
+
+- [Transaction Errors](#transaction-errors)
+  - [Overspend](#overspend)
+  - [Transaction Already in Ledger](#transaction-already-in-ledger)
+  - [Transaction Pool Full](#transaction-pool-full)
+  - [Fee Too Low](#fee-too-low)
+  - [Round Out of Range](#round-out-of-range)
+  - [Invalid Group](#invalid-group)
+  - [Group Size Limit](#group-size-limit)
+- [Asset Errors](#asset-errors)
+  - [Asset Not Found](#asset-not-found)
+  - [Asset Not Opted In](#asset-not-opted-in)
+  - [Asset Frozen](#asset-frozen)
+  - [Clawback Not Authorized](#clawback-not-authorized)
+  - [Cannot Close Asset](#cannot-close-asset)
+- [Account Errors](#account-errors)
+  - [Account Not Found](#account-not-found)
+  - [Invalid Address](#invalid-address)
+  - [Wrong Network](#wrong-network)
+- [SDK Errors](#sdk-errors)
+- [Application Errors](#application-errors)
+- [Debugging Tips](#debugging-tips)
+
+## Transaction Errors
+
+### Overspend
+
+```
+TransactionPool.Remember: transaction TXID: overspend (account ADDRESS, data {_struct:{} Status:Offline MicroAlgos:{Raw:1000} ...})
+```
+
+**Cause:** Sender account has insufficient balance for amount + fee + minimum balance.
+
+**Minimum balance requirements:**
+| Item | MBR |
+|------|-----|
+| Base account | 100,000 microAlgo |
+| Each opted-in asset | +100,000 microAlgo |
+| Each created asset | +100,000 microAlgo |
+| Each opted-in app | +100,000 microAlgo |
+| Each created app | +100,000 microAlgo |
+| App local state per schema | Varies |
+| Box storage | 2,500 + 400 * size |
+
+**Fix:**
+```typescript
+// Calculate available balance
+const accountInfo = await algorand.account.getInformation(address)
+const available = accountInfo.amount - accountInfo.minBalance
+```
+
+### Transaction Already in Ledger
+
+```
+TransactionPool.Remember: transaction already in ledger: TXID
+```
+
+**Cause:** Duplicate transaction submitted (same txn ID).
+
+**Fix:** Check if transaction exists before retrying:
+```typescript
+try {
+  const result = await algorand.client.algod.pendingTransactionInformation(txId).do()
+  // Transaction exists
+} catch {
+  // Safe to retry
+}
+```
+
+### Transaction Pool Full
+
+```
+TransactionPool.Remember: transaction pool is full
+```
+
+**Cause:** Node's transaction pool at capacity.
+
+**Fix:**
+1. Wait and retry with exponential backoff
+2. Increase fee to prioritize transaction
+3. Try a different node
+
+### Fee Too Low
+
+```
+TransactionPool.Remember: transaction TXID: fee X below threshold Y
+```
+
+**Cause:** Transaction fee below minimum (usually 1000 microAlgo).
+
+**Fix:**
+```typescript
+await algorand.send.payment({
+  sender: sender,
+  receiver: receiver,
+  amount: algo(1),
+  staticFee: microAlgo(1000),  // Minimum fee
+})
+```
+
+### Round Out of Range
+
+```
+TransactionPool.Remember: transaction TXID: round X outside of Y-Z range
+```
+
+**Cause:** Transaction's validity window expired or is in the future.
+
+**Fix:**
+```typescript
+await algorand.send.payment({
+  sender: sender,
+  receiver: receiver,
+  amount: algo(1),
+  validityWindow: 1000,  // Valid for 1000 rounds (~1 hour)
+})
+```
+
+### Invalid Group
+
+```
+TransactionPool.Remember: transaction TXID: bad group assignment
+```
+
+**Cause:** Transaction claims to be part of a group but has wrong group ID.
+
+**Fix:** Use AlgoKit Utils for proper grouping:
+```typescript
+await algorand
+  .newGroup()
+  .addPayment({ sender, receiver, amount: algo(1) })
+  .addAssetOptIn({ sender, assetId: 12345n })
+  .send()
+```
+
+### Group Size Limit
+
+```
+cannot send transaction group with more than 16 transactions
+```
+
+**Cause:** Transaction group exceeds 16 transaction limit.
+
+**Fix:** Split into multiple groups or optimize to fewer transactions.
+
+## Asset Errors
+
+### Asset Not Found
+
+```
+asset ASSET_ID does not exist
+```
+
+**Cause:** Asset ID doesn't exist on the network.
+
+**Common causes:**
+- Wrong network (TestNet vs MainNet)
+- Asset was deleted
+- Typo in asset ID
+
+**Fix:** Verify asset exists:
+```typescript
+const assetInfo = await algorand.client.algod.getAssetByID(assetId).do()
+```
+
+### Asset Not Opted In
+
+```
+asset ASSET_ID missing from ACCOUNT_ADDRESS
+```
+
+**Cause:** Receiving account hasn't opted into the asset.
+
+**Fix:**
+```typescript
+await algorand.send.assetOptIn({
+  sender: receiverAddress,
+  assetId: assetId,
+})
+```
+
+### Asset Frozen
+
+```
+asset ASSET_ID frozen in ACCOUNT_ADDRESS
+```
+
+**Cause:** Account's holding of this asset is frozen.
+
+**Fix:** Asset freeze manager must unfreeze the account.
+
+### Clawback Not Authorized
+
+```
+only clawback address can clawback
+```
+
+**Cause:** Attempting clawback without being the clawback address.
+
+**Fix:** Only the designated clawback address can perform clawbacks.
+
+### Cannot Close Asset
+
+```
+cannot close asset: ACCOUNT_ADDRESS still has X units
+```
+
+**Cause:** Trying to opt out while still holding units.
+
+**Fix:** Transfer all units before opting out:
+```typescript
+// First transfer all units
+await algorand.send.assetTransfer({
+  sender: account,
+  receiver: creatorOrOther,
+  assetId: assetId,
+  amount: balance,  // All remaining
+})
+
+// Then opt out
+await algorand.send.assetOptOut({
+  sender: account,
+  assetId: assetId,
+  creator: creatorAddress,
+})
+```
+
+## Account Errors
+
+### Account Not Found
+
+```
+account ADDRESS not found
+```
+
+**Cause:** Account doesn't exist (never funded).
+
+**Note:** Algorand accounts must receive at least minimum balance to exist.
+
+**Fix:**
+```typescript
+await algorand.send.payment({
+  sender: funder.address,
+  receiver: newAccount.address,
+  amount: microAlgo(100_000),  // Minimum
+})
+```
+
+### Invalid Address
+
+```
+invalid address: ADDRESS
+```
+
+**Cause:** Malformed Algorand address.
+
+**Valid address format:**
+- 58 characters
+- Base32 encoded
+- Includes checksum
+
+**Verify address:**
+```typescript
+import { isValidAddress } from 'algosdk'
+if (!isValidAddress(address)) {
+  throw new Error('Invalid address')
+}
+```
+
+### Wrong Network
+
+```
+genesis hash mismatch
+```
+
+**Cause:** Transaction built for different network than target.
+
+**Fix:**
+```typescript
+// For TestNet
+const algorand = AlgorandClient.testNet()
+
+// For MainNet
+const algorand = AlgorandClient.mainNet()
+
+// Check network
+const params = await algorand.client.algod.getTransactionParams().do()
+console.log('Network:', params.genesisID)  // testnet-v1.0, mainnet-v1.0
+```
+
+## SDK Errors
+
+### AlgodHTTPError
+
+```
+AlgodHTTPError: Network request error. Received status 401
+```
+
+**Common status codes:**
+| Status | Meaning | Fix |
+|--------|---------|-----|
+| 401 | Unauthorized | Check API token |
+| 404 | Not found | Check server URL |
+| 500 | Server error | Node issue, retry |
+| 503 | Unavailable | Node overloaded, retry |
+
+**Fix for 401:**
+```typescript
+const algorand = AlgorandClient.fromConfig({
+  algodConfig: {
+    server: 'https://testnet-api.algonode.cloud',
+    port: '443',
+    token: '',  // AlgoNode doesn't require token
+  }
+})
+```
+
+### Timeout Waiting for Confirmation
+
+```
+Timeout waiting for transaction TXID to be confirmed
+```
+
+**Cause:** Transaction not confirmed within wait rounds.
+
+**Fix:**
+```typescript
+const result = await algorand.send.payment(
+  { sender, receiver, amount: algo(1) },
+  { maxRoundsToWaitForConfirmation: 10 }  // Wait longer
+)
+```
+
+### Connection Refused
+
+```
+fetch failed: ECONNREFUSED
+```
+
+**Cause:** Cannot connect to Algorand node.
+
+**Fix:**
+1. For LocalNet: Ensure AlgoKit LocalNet is running (`algokit localnet start`)
+2. For public networks: Check internet connection
+3. Verify server URL is correct
+
+## Application Errors
+
+### Application Not Found
+
+```
+application APPID does not exist
+```
+
+**Cause:** App ID doesn't exist on the network.
+
+**Fix:**
+```typescript
+const appInfo = await algorand.client.algod.getApplicationByID(appId).do()
+```
+
+### Not Opted Into Application
+
+```
+address ADDRESS has not opted in to application APPID
+```
+
+**Cause:** Account trying to access local state without opt-in.
+
+**Fix:**
+```typescript
+await algorand.send.appCall({
+  sender: userAddress,
+  appId: appId,
+  onComplete: OnComplete.OptIn,
+})
+```
+
+### Application Creator Only
+
+```
+cannot update or delete application: only creator can modify
+```
+
+**Cause:** Attempting to modify app without being creator.
+
+**Fix:**
+```typescript
+const appInfo = await algorand.app.getById(appId)
+if (sender !== appInfo.creator) {
+  throw new Error('Only creator can modify')
+}
+```
+
+## Debugging Tips
+
+### Enable Verbose Logging
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+Config.configure({ debug: true })
+```
+
+### Check Transaction Status
+
+```typescript
+// Check pending transaction
+const pending = await algorand.client.algod.pendingTransactionInformation(txId).do()
+console.log('Pool error:', pending.poolError)
+
+// Check confirmed transaction
+const confirmed = await algorand.client.indexer.lookupTransactionByID(txId).do()
+```
+
+### Simulate Before Sending
+
+```typescript
+const result = await algorand
+  .newGroup()
+  .addPayment({ sender, receiver, amount: algo(1) })
+  .simulate()
+
+if (result.simulateResponse.txnGroups[0].failureMessage) {
+  console.error('Would fail:', result.simulateResponse.txnGroups[0].failureMessage)
+}
+```
+
+## References
+
+- [Transaction Structure](https://dev.algorand.co/concepts/transactions/structure/)
+- [Account Management](https://dev.algorand.co/concepts/accounts/)
+- [Asset Overview](https://dev.algorand.co/concepts/assets/)
+- [AlgoKit Utils TS Debugging](https://dev.algorand.co/algokit/utils/typescript/debugging/)