@goplausible/openclaw-algorand-plugin 0.5.0

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

@@ -0,0 +1,430 @@
+# Transaction & Account Errors (Python)
+
+Python-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:**
+```python
+# Calculate available balance
+account_info = algorand.account.get_information(address)
+available = account_info.amount - account_info.min_balance
+```
+
+### 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:
+```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
+))
+```
+
+### 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:**
+```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:
+```python
+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:
+```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:**
+```python
+algorand.send.asset_opt_in(AssetOptInParams(
+    sender=receiver_address,
+    asset_id=asset_id,
+))
+```
+
+### 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,
+))
+```
+
+## 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:**
+```python
+algorand.send.payment(PaymentParams(
+    sender=funder.address,
+    receiver=new_account.address,
+    amount=AlgoAmount(micro_algo=100_000),  # Minimum
+))
+```
+
+### Invalid Address
+
+```
+invalid address: ADDRESS
+```
+
+**Cause:** Malformed Algorand address.
+
+**Valid address format:**
+- 58 characters
+- Base32 encoded
+- Includes checksum
+
+**Verify 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:**
+```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
+    )
+)
+```
+
+### Timeout Waiting for Confirmation
+
+```
+Timeout waiting for transaction TXID to be confirmed
+```
+
+**Cause:** Transaction not confirmed within wait rounds.
+
+**Fix:**
+```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:**
+```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,
+))
+```
+
+### Application Creator Only
+
+```
+cannot update or delete application: only creator can modify
+```
+
+**Cause:** Attempting to modify app without being creator.
+
+**Fix:**
+```python
+app_info = algorand.app.get_by_id(app_id)
+if sender != app_info.creator:
+    raise Error("Only creator can modify")
+```
+
+## Debugging Tips
+
+### Enable Verbose Logging
+
+```python
+import logging
+logging.getLogger("algokit").setLevel(logging.DEBUG)
+```
+
+### Check Transaction Status
+
+```python
+# Check pending transaction
+pending = algorand.client.algod.pending_transaction_info(tx_id)
+print("Pool error:", pending.get("pool-error", ""))
+```
+
+### Simulate Before Sending
+
+```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-python/references/troubleshoot-errors.md

@@ -0,0 +1,46 @@
+# Troubleshoot Errors (Python)
+
+Diagnose and resolve common Algorand development errors when working with Python and AlgoKit Utils Python.
+
+## Error References
+
+| Category | Description | Reference |
+|----------|-------------|-----------|
+| Contract Errors | Assert failures, opcode budget, ABI issues, state errors | [troubleshoot-errors-contract.md](./troubleshoot-errors-contract.md) |
+| Transaction Errors | Overspend, invalid params, group issues, asset/account errors | [troubleshoot-errors-transaction.md](./troubleshoot-errors-transaction.md) |
+
+## Python Debugging Quick Start
+
+### Enable Debug Logging
+
+```python
+import logging
+logging.getLogger("algokit").setLevel(logging.DEBUG)
+```
+
+### Catch and Inspect LogicError
+
+```python
+from algokit_utils import LogicError
+
+try:
+    app_client.send.my_method(value=0)
+except LogicError as e:
+    print(e)       # Shows: assert failed at contracts/my_contract.py:45
+    print(e.pc)    # Program counter: 123
+    print(e.line)  # Source line number
+```
+
+### Check Transaction Status
+
+```python
+# Check pending transaction
+pending = algorand.client.algod.pending_transaction_info(tx_id)
+print("Pool error:", pending.get("pool-error", ""))
+```
+
+## How to Proceed
+
+1. **Find your error** in the contract or transaction error references
+2. **Understand the cause** from the explanation
+3. **Apply the Python fix** from the code examples