@goplausible/openclaw-algorand-plugin 0.5.0

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

@@ -0,0 +1,599 @@
+# Transaction & Account Errors
+
+Common errors when sending transactions and managing accounts on Algorand.
+
+## 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:**
+1. Fund the sender account
+2. Reduce transaction amount
+3. Account for MBR when calculating available balance:
+
+```python
+# Calculate available balance
+account_info = algorand.account.get_information(address)
+available = account_info.amount - account_info.min_balance
+```
+
+```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).
+
+**Common causes:**
+- Retrying a transaction that already succeeded
+- Using same lease within validity window
+- Network latency causing duplicate submission
+
+**Fix:** Check if transaction exists before retrying:
+```typescript
+try {
+  const result = await algorand.client.algod.pendingTransactionInformation(txId).do()
+  // Transaction exists
+} catch {
+  // Safe to retry
+}
+```
+
+```python
+try:
+    result = algorand.client.algod.pending_transaction_info(tx_id)
+    # Transaction exists
+except Exception:
+    # Safe to retry
+    pass
+```
+
+### 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:**
+```python
+algorand.send.payment(PaymentParams(
+    sender=sender,
+    receiver=receiver,
+    amount=AlgoAmount(algo=1),
+    static_fee=AlgoAmount(micro_algo=1000),  # Minimum fee
+))
+```
+
+```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
+// Set appropriate validity window
+await algorand.send.payment({
+  sender: sender,
+  receiver: receiver,
+  amount: algo(1),
+  validityWindow: 1000,  // Valid for 1000 rounds (~1 hour)
+})
+```
+
+```python
+algorand.send.payment(PaymentParams(
+    sender=sender,
+    receiver=receiver,
+    amount=AlgoAmount(algo=1),
+    validity_window=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
+// Correct grouping
+await algorand
+  .newGroup()
+  .addPayment({ sender, receiver, amount: algo(1) })
+  .addAssetOptIn({ sender, assetId: 12345n })
+  .send()
+```
+
+```python
+# Correct grouping
+algorand.new_group()
+    .add_payment(PaymentParams(sender=sender, receiver=receiver, amount=AlgoAmount(algo=1)))
+    .add_asset_opt_in(AssetOptInParams(sender=sender, asset_id=12345))
+    .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()
+```
+
+```python
+asset_info = algorand.client.algod.asset_info(asset_id)
+```
+
+### Asset Not Opted In
+
+```
+asset ASSET_ID missing from ACCOUNT_ADDRESS
+```
+
+**Cause:** Receiving account hasn't opted into the asset.
+
+**Fix:** Opt in before transfer:
+```python
+algorand.send.asset_opt_in(AssetOptInParams(
+    sender=receiver_address,
+    asset_id=asset_id,
+))
+```
+
+```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:
+```python
+# First transfer all units
+algorand.send.asset_transfer(AssetTransferParams(
+    sender=account,
+    receiver=creator_or_other,
+    asset_id=asset_id,
+    amount=balance,  # All remaining
+))
+
+# Then opt out
+algorand.send.asset_opt_out(AssetOptOutParams(
+    sender=account,
+    asset_id=asset_id,
+    creator=creator_address,
+))
+```
+
+```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:** Fund the account:
+```python
+algorand.send.payment(PaymentParams(
+    sender=funder.address,
+    receiver=new_account.address,
+    amount=AlgoAmount(micro_algo=100_000),  # Minimum
+))
+```
+
+```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')
+}
+```
+
+```python
+from algosdk import encoding
+if not encoding.is_valid_address(address):
+    raise ValueError("Invalid address")
+```
+
+### Wrong Network
+
+```
+genesis hash mismatch
+```
+
+**Cause:** Transaction built for different network than target.
+
+**Fix:** Ensure AlgorandClient connects to correct network:
+```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
+```
+
+```python
+# For TestNet
+algorand = AlgorandClient.test_net()
+
+# For MainNet
+algorand = AlgorandClient.main_net()
+```
+
+## 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:**
+```python
+algorand = AlgorandClient.from_config(
+    algod_config=AlgoClientNetworkConfig(
+        server="https://testnet-api.algonode.cloud",
+        port="443",
+        token="",  # AlgoNode doesn't require token
+    )
+)
+```
+
+```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.
+
+**Possible reasons:**
+- Transaction rejected (check node logs)
+- Fee too low during congestion
+- Network issues
+
+**Fix:** Increase wait time or check status:
+```typescript
+const result = await algorand.send.payment(
+  { sender, receiver, amount: algo(1) },
+  { maxRoundsToWaitForConfirmation: 10 }  // Wait longer
+)
+```
+
+```python
+result = algorand.send.payment(PaymentParams(
+    sender=sender,
+    receiver=receiver,
+    amount=AlgoAmount(algo=1),
+    max_rounds_to_wait_for_confirmation=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:** Verify app exists or deploy it:
+```typescript
+const appInfo = await algorand.client.algod.getApplicationByID(appId).do()
+```
+
+```python
+app_info = algorand.client.algod.application_info(app_id)
+```
+
+### Not Opted Into Application
+
+```
+address ADDRESS has not opted in to application APPID
+```
+
+**Cause:** Account trying to access local state without opt-in.
+
+**Fix:**
+```python
+algorand.send.app_call(AppCallParams(
+    sender=user_address,
+    app_id=app_id,
+    on_complete=OnComplete.OptIn,
+))
+```
+
+```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:** Only the app creator can update/delete. Check creator:
+```python
+app_info = algorand.app.get_by_id(app_id)
+if sender != app_info.creator:
+    raise Error("Only creator can modify")
+```
+
+```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 })
+```
+
+```python
+import logging
+logging.getLogger("algokit").setLevel(logging.DEBUG)
+```
+
+### 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()
+```
+
+```python
+# Check pending transaction
+pending = algorand.client.algod.pending_transaction_info(tx_id)
+print("Pool error:", pending.get("pool-error", ""))
+```
+
+### 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)
+}
+```
+
+```python
+result = algorand.new_group() \
+    .add_payment(PaymentParams(sender=sender, receiver=receiver, amount=AlgoAmount(algo=1))) \
+    .simulate()
+```
+
+## 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 Debugging](https://dev.algorand.co/algokit/utils/typescript/debugging/)

package/skills/algorand-development/references/troubleshoot-errors.md

@@ -0,0 +1,105 @@
+# Troubleshoot Errors
+
+Diagnose and resolve common Algorand development errors.
+
+## Error Categories
+
+| Category | Common Causes | Reference |
+|----------|---------------|-----------|
+| Contract Errors | Assert failures, opcode budget, invalid operations, ABI issues, state errors | [troubleshoot-errors-contract.md](./troubleshoot-errors-contract.md) |
+| Transaction Errors | Overspend, invalid params, group issues, asset errors, SDK errors | [troubleshoot-errors-transaction.md](./troubleshoot-errors-transaction.md) |
+
+## Quick Diagnosis Flow
+
+1. **Identify the error type** from the message
+2. **Check the error code** if present (e.g., `pc=123`)
+3. **Find the root cause** using the reference docs
+4. **Apply the fix** from the common solutions
+
+## Common Error Patterns
+
+### Logic Eval Error (Contract Failure)
+
+```
+logic eval error: assert failed pc=123
+```
+
+**Cause:** An `assert` statement in the smart contract evaluated to false.
+
+**Debug steps:**
+1. The `pc=123` indicates the program counter where failure occurred
+2. Use source maps to find the exact line in your code
+3. Check the assertion condition and input values
+4. Use AlgoKit Utils LogicError for automatic source mapping
+
+### Transaction Rejected (Overspend)
+
+```
+TransactionPool.Remember: transaction TXID: overspend
+```
+
+**Cause:** Sender account has insufficient balance for amount + fee + minimum balance requirement.
+
+**Debug steps:**
+1. Check the sender's account balance
+2. Calculate the minimum balance requirement (base 100,000 microAlgo + opted-in assets/apps)
+3. Ensure `available balance = total balance - minimum balance` covers the transaction amount + fee
+
+### Opcode Budget Exceeded
+
+```
+logic eval error: dynamic cost budget exceeded
+```
+
+**Cause:** Contract exceeded the 700 opcode budget per app call.
+
+**Solutions:**
+- Add more app calls to the group for additional budget (pooled up to 11,200 with 16 calls)
+- Optimize contract logic to reduce operations
+- Split complex operations across multiple calls
+
+### Asset Not Opted In
+
+```
+asset ASSET_ID missing from ACCOUNT_ADDRESS
+```
+
+**Cause:** The receiving account has not opted into the asset.
+
+**Solution:** Have the receiver send a 0-amount asset transfer to themselves before any transfers are attempted.
+
+### Application Not Opted In
+
+```
+address ADDRESS has not opted in to application APPID
+```
+
+**Cause:** Account trying to access local state without opting in to the application.
+
+**Solution:** The account must send an opt-in transaction (OnComplete.OptIn) before local state can be accessed.
+
+### SDK Connection Errors
+
+```
+AlgodHTTPError: Network request error. Received status 401
+```
+
+**Cause:** Authentication or connectivity issue with the Algorand node.
+
+**Debug steps:**
+1. Check the API token configuration
+2. Verify the server URL is correct
+3. Ensure the node is running (for LocalNet: `algokit localnet start`)
+
+## How to Proceed
+
+1. **Find your error** in the category references above
+2. **Understand the cause** from the explanation
+3. **Apply the solution** from the code examples
+
+## References
+
+- [Contract Errors Reference](./troubleshoot-errors-contract.md) - Smart contract and logic errors
+- [Transaction Errors Reference](./troubleshoot-errors-transaction.md) - Transaction and account errors
+- [Debugging Guide](https://dev.algorand.co/concepts/smart-contracts/debugging/)
+- [Error Handling in AlgoKit Utils](https://dev.algorand.co/algokit/utils/typescript/debugging/)