@goplausible/openclaw-algorand-plugin 0.5.0

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

@@ -0,0 +1,56 @@
+# Troubleshoot Errors (TypeScript)
+
+Diagnose and resolve common Algorand development errors when working with TypeScript and AlgoKit Utils TypeScript.
+
+## 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) |
+
+## TypeScript Debugging Quick Start
+
+### Enable Debug Logging
+
+```typescript
+import { Config } from '@algorandfoundation/algokit-utils'
+Config.configure({ debug: true })
+```
+
+### Simulate with Execution Trace
+
+```typescript
+// Simulate to get execution trace before sending
+const result = await algorand.newGroup()
+  .addAppCallMethodCall(params)
+  .simulate({ execTraceConfig: { enable: true } })
+
+console.log(result.simulateResponse.txnGroups[0].txnResults[0].execTrace)
+```
+
+### Catch and Inspect Errors
+
+```typescript
+try {
+  await appClient.send.myMethod({ args: { value: 0 } })
+} catch (e) {
+  // AlgoKit Utils automatically includes source-mapped error info
+  // Error includes: "assert failed at contracts/my_contract.py:45"
+  console.error(e)
+}
+```
+
+### Check Transaction Status
+
+```typescript
+// Check pending transaction
+const pending = await algorand.client.algod.pendingTransactionInformation(txId).do()
+console.log('Pool error:', pending.poolError)
+```
+
+## How to Proceed
+
+1. **Find your error** in the contract or transaction error references
+2. **Understand the cause** from the explanation
+3. **Apply the TypeScript fix** from the code examples

package/skills/algorand-typescript/references/use-algokit-utils-reference.md

@@ -0,0 +1,342 @@
+# AlgorandClient (TypeScript)
+
+The main entry point for interacting with Algorand in TypeScript applications.
+
+## Installation
+
+```bash
+npm install @algorandfoundation/algokit-utils
+```
+
+## Creating an AlgorandClient
+
+```typescript
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+
+// From environment variables (recommended for production)
+const algorand = AlgorandClient.fromEnvironment()
+
+// Default LocalNet configuration
+const algorand = AlgorandClient.defaultLocalNet()
+
+// TestNet using AlgoNode free tier
+const algorand = AlgorandClient.testNet()
+
+// MainNet using AlgoNode free tier
+const algorand = AlgorandClient.mainNet()
+
+// From existing clients
+const algorand = AlgorandClient.fromClients({ algod, indexer, kmd })
+
+// From custom configuration
+const algorand = AlgorandClient.fromConfig({
+  algodConfig: {
+    server: 'http://localhost',
+    port: '4001',
+    token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',
+  },
+})
+```
+
+## Accessing SDK Clients
+
+```typescript
+const algodClient = algorand.client.algod
+const indexerClient = algorand.client.indexer
+const kmdClient = algorand.client.kmd
+```
+
+## Account Management
+
+### Getting Accounts
+
+```typescript
+// From environment variable (DEPLOYER_MNEMONIC)
+const deployer = await algorand.account.fromEnvironment('DEPLOYER')
+
+// Random account (for testing)
+const random = algorand.account.random()
+
+// From mnemonic
+const account = algorand.account.fromMnemonic('abandon abandon...')
+
+// From KMD (LocalNet)
+const kmdAccount = await algorand.account.fromKmd('wallet-name', 'password')
+```
+
+### Registering Signers
+
+```typescript
+// Register a signer for automatic signing
+algorand.setSignerFromAccount(account)
+
+// Set default signer for all transactions
+algorand.setDefaultSigner(account.signer)
+```
+
+## Sending Transactions
+
+### Single Transactions
+
+```typescript
+import { algo } from '@algorandfoundation/algokit-utils'
+
+// Payment
+const result = await algorand.send.payment({
+  sender: 'SENDERADDRESS',
+  receiver: 'RECEIVERADDRESS',
+  amount: algo(1),
+})
+
+// Asset transfer
+await algorand.send.assetTransfer({
+  sender: 'SENDERADDRESS',
+  receiver: 'RECEIVERADDRESS',
+  assetId: 12345n,
+  amount: 100n,
+})
+
+// Asset opt-in
+await algorand.send.assetOptIn({
+  sender: 'SENDERADDRESS',
+  assetId: 12345n,
+})
+
+// Asset create
+const createResult = await algorand.send.assetCreate({
+  sender: 'SENDERADDRESS',
+  total: 1000000n,
+  decimals: 6,
+  assetName: 'My Token',
+  unitName: 'MTK',
+})
+const assetId = createResult.assetId
+```
+
+### Transaction Groups
+
+```typescript
+const result = await algorand
+  .newGroup()
+  .addPayment({
+    sender: 'SENDERADDRESS',
+    receiver: 'RECEIVERADDRESS',
+    amount: algo(1),
+  })
+  .addAssetOptIn({
+    sender: 'SENDERADDRESS',
+    assetId: 12345n,
+  })
+  .send()
+```
+
+### Creating Transactions (Without Sending)
+
+```typescript
+const payment = await algorand.createTransaction.payment({
+  sender: 'SENDERADDRESS',
+  receiver: 'RECEIVERADDRESS',
+  amount: algo(1),
+})
+// payment is an unsigned algosdk.Transaction
+```
+
+## Common Transaction Parameters
+
+All transactions support these common parameters:
+
+```typescript
+await algorand.send.payment({
+  sender: 'SENDERADDRESS',
+  receiver: 'RECEIVERADDRESS',
+  amount: algo(1),
+
+  // Optional parameters
+  note: 'My note',
+  lease: 'unique-lease-id',
+  rekeyTo: 'NEWADDRESS',
+
+  // Fee management
+  staticFee: algo(0.001),
+  extraFee: algo(0.001),  // For covering inner txn fees
+  maxFee: algo(0.01),
+
+  // Validity
+  validityWindow: 1000,
+  firstValidRound: 12345n,
+  lastValidRound: 12445n,
+})
+```
+
+## App Calls
+
+### Using Typed App Clients (Recommended)
+
+```typescript
+// Get typed factory from generated client
+const factory = algorand.client.getTypedAppFactory(MyContractFactory)
+
+// Deploy
+const { appClient, result } = await factory.deploy({
+  sender: deployer.addr,
+})
+
+// Call methods
+const response = await appClient.send.myMethod({
+  sender: deployer.addr,
+  args: { param1: 'value' },
+})
+```
+
+### Generic App Calls
+
+```typescript
+await algorand.send.appCallMethodCall({
+  sender: 'SENDERADDRESS',
+  appId: 12345n,
+  method: algosdk.ABIMethod.fromSignature('hello(string)string'),
+  args: ['World'],
+})
+```
+
+## Send Parameters
+
+Control execution behavior when sending:
+
+```typescript
+await algorand.send.payment(
+  {
+    sender: 'SENDERADDRESS',
+    receiver: 'RECEIVERADDRESS',
+    amount: algo(1),
+  },
+  {
+    // Wait for confirmation
+    maxRoundsToWaitForConfirmation: 5,
+
+    // Suppress logging
+    suppressLog: true,
+
+    // Auto-populate app call resources
+    populateAppCallResources: true,
+
+    // Auto-calculate inner txn fees
+    coverAppCallInnerTransactionFees: true,
+  }
+)
+```
+
+## Amount Helpers
+
+```typescript
+import { algo, microAlgo } from '@algorandfoundation/algokit-utils'
+
+algo(1)           // 1 Algo = 1,000,000 microAlgo
+algo(0.5)         // 0.5 Algo = 500,000 microAlgo
+microAlgo(1000)   // 1000 microAlgo
+
+// Extension method syntax (alternative)
+(1).algo()        // 1 Algo = 1,000,000 microAlgo
+(100).microAlgo() // 100 microAlgo
+```
+
+## Testing with algorandFixture
+
+For testing, use `algorandFixture` to manage LocalNet lifecycle:
+
+```typescript
+import { algorandFixture, AlgorandFixtureConfig } from '@algorandfoundation/algokit-utils/testing'
+import { Config } from '@algorandfoundation/algokit-utils'
+
+// Basic setup
+const localnet = algorandFixture()
+
+// With custom configuration
+const localnet = algorandFixture({
+  testAccountFunding: algo(100),  // Fund test accounts with 100 Algo
+  algodConfig: {
+    server: 'http://localhost',
+    port: '4001',
+    token: 'aaaa...',
+  },
+} satisfies AlgorandFixtureConfig)
+
+// In tests
+beforeAll(() => {
+  Config.configure({ debug: true })
+})
+beforeEach(localnet.newScope, 10_000)  // 10s timeout for LocalNet setup
+
+// Access algorand client
+const { algorand, testAccount } = localnet.context
+```
+
+### Log Capture Fixture
+
+Use `algoKitLogCaptureFixture` to capture and verify logs in tests:
+
+```typescript
+import { algoKitLogCaptureFixture } from '@algorandfoundation/algokit-utils/testing'
+
+const logs = algoKitLogCaptureFixture()
+
+beforeEach(logs.beforeEach)
+afterEach(logs.afterEach)
+
+test('should log transaction', async () => {
+  // ... perform operations
+  expect(logs.testLogger.getLogSnapshot()).toMatchInlineSnapshot()
+})
+```
+
+## Common Patterns
+
+### Fund an Account
+
+```typescript
+await algorand.send.payment({
+  sender: funderAccount.addr,
+  receiver: newAccount.addr,
+  amount: algo(10),
+})
+```
+
+### Create and Fund in One Group
+
+```typescript
+const newAccount = algorand.account.random()
+
+await algorand
+  .newGroup()
+  .addPayment({
+    sender: funder.addr,
+    receiver: newAccount.addr,
+    amount: algo(1),
+  })
+  .addAssetOptIn({
+    sender: newAccount.addr,
+    assetId: 12345n,
+  })
+  .send()
+```
+
+### Deploy and Fund Contract
+
+```typescript
+const factory = algorand.client.getTypedAppFactory(MyContractFactory)
+const { appClient } = await factory.deploy({ sender: deployer.addr })
+
+// Fund the app account for box storage
+await algorand.send.payment({
+  sender: deployer.addr,
+  receiver: appClient.appAddress,
+  amount: algo(1),
+})
+```
+
+## References
+
+- [AlgoKit Utils TS Overview](https://dev.algorand.co/algokit/utils/typescript/overview/)
+- [AlgorandClient API](https://dev.algorand.co/reference/algokit-utils-ts/api/classes/types_algorand_clientalgorandclient/)
+- [Transaction Composer](https://dev.algorand.co/algokit/utils/typescript/transaction-composer/)
+- [Account Management](https://dev.algorand.co/algokit/utils/typescript/account/)

package/skills/algorand-typescript/references/use-algokit-utils.md

@@ -0,0 +1,74 @@
+# AlgoKit Utils (TypeScript)
+
+AlgoKit Utils for TypeScript is the primary library for building Algorand applications in TypeScript/JavaScript. It provides a high-level, ergonomic interface via the `AlgorandClient` class, which is the single entry point for interacting with the Algorand network -- sending transactions, managing accounts, deploying smart contracts, and more.
+
+## Installation
+
+```bash
+npm install @algorandfoundation/algokit-utils
+```
+
+## Quick Start
+
+### 1. Create an AlgorandClient
+
+```typescript
+import { AlgorandClient } from '@algorandfoundation/algokit-utils'
+
+// Connect to LocalNet (development)
+const algorand = AlgorandClient.defaultLocalNet()
+
+// Connect to TestNet
+const algorand = AlgorandClient.testNet()
+
+// Connect to MainNet
+const algorand = AlgorandClient.mainNet()
+
+// From environment variables (recommended for production)
+const algorand = AlgorandClient.fromEnvironment()
+```
+
+### 2. Get and Register an Account
+
+```typescript
+// Get a random account (testing)
+const account = algorand.account.random()
+
+// From environment variable (e.g. DEPLOYER_MNEMONIC)
+const deployer = await algorand.account.fromEnvironment('DEPLOYER')
+
+// Register the signer so transactions are automatically signed
+algorand.setSignerFromAccount(account)
+```
+
+### 3. Send a Transaction
+
+```typescript
+import { algo } from '@algorandfoundation/algokit-utils'
+
+const result = await algorand.send.payment({
+  sender: account.addr,
+  receiver: 'RECEIVERADDRESS',
+  amount: algo(1),
+})
+```
+
+## Key Rules
+
+1. **Always use `AlgorandClient`** as the single entry point. Do not instantiate lower-level SDK clients directly.
+2. **Use `AlgorandClient.fromEnvironment()`** for production deployments and CI/CD pipelines.
+3. **Register signers** with `algorand.setSignerFromAccount(account)` before sending transactions so signing is handled automatically.
+4. **Use the `algo()` and `microAlgo()` helpers** for amounts instead of raw numbers to avoid unit conversion errors.
+
+## Reference
+
+For the full AlgorandClient API covering client creation, account management, transaction sending, app calls, transaction groups, amount helpers, testing fixtures, and common patterns:
+
+[AlgorandClient Reference](./use-algokit-utils-reference.md)
+
+## External Links
+
+- [AlgoKit Utils TS Overview](https://dev.algorand.co/algokit/utils/typescript/overview/)
+- [AlgorandClient API Reference](https://dev.algorand.co/reference/algokit-utils-ts/api/classes/types_algorand_clientalgorandclient/)
+- [Transaction Composer](https://dev.algorand.co/algokit/utils/typescript/transaction-composer/)
+- [Account Management](https://dev.algorand.co/algokit/utils/typescript/account/)

package/skills/algorand-x402-python/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: algorand-x402-python
+description: Comprehensive guide for building x402 HTTP-native payment applications on Algorand using Python. This is the parent skill that aggregates all Python x402 sub-skills. Use when working with x402 payments in Python, building clients, servers, facilitators, or Bazaar discovery with Algorand x402, or when explaining x402 concepts to Python developers. Strong triggers include "x402 Python", "x402 Algorand Python", "x402-avm Python", "payment protocol Python", "402 payment Python", "x402 client httpx requests", "x402 server FastAPI Flask", "x402 facilitator Python", "x402 Bazaar discovery", "x402 core avm Python", "explain x402 Python", "teach x402".
+---
+
+# x402 on Algorand - Python
+
+This is the aggregated parent skill for all x402 HTTP-native payment protocol skills targeting Python. Use the reference files below to find detailed guidance for each component.
+
+## Python Quick Start
+
+```bash
+# Minimal AVM support
+pip install x402-avm[avm]
+
+# Server frameworks (pick one)
+pip install x402-avm[avm,fastapi]
+pip install x402-avm[avm,flask]
+
+# HTTP clients (pick one)
+pip install x402-avm[avm,httpx]
+pip install x402-avm[avm,requests]
+
+# Everything
+pip install x402-avm[all]
+```
+
+### Register AVM Scheme
+
+Every component registers the AVM exact scheme unconditionally — no environment variable guards:
+
+```python
+# Client
+from x402_avm.mechanisms.avm.exact.client import register_exact_avm_scheme
+register_exact_avm_scheme(client, signer=my_signer)
+
+# Server
+from x402_avm.mechanisms.avm.exact.server import register_exact_avm_scheme
+register_exact_avm_scheme(server)
+
+# Facilitator
+from x402_avm.mechanisms.avm.exact.facilitator import register_exact_avm_facilitator
+register_exact_avm_facilitator(facilitator, signer=my_signer, networks=ALGORAND_TESTNET_CAIP2)
+```
+
+### Python algosdk Encoding
+
+Python algosdk's `msgpack_decode()` expects base64 strings, `msgpack_encode()` returns base64 strings. Boundary conversion: `msgpack_decode(base64.b64encode(raw_bytes).decode())` / `base64.b64decode(msgpack_encode(obj))`.
+
+## Reference Guide
+
+Navigate to the appropriate reference based on your task. Each topic has three files:
+- **`{name}.md`** — Step-by-step implementation guide
+- **`{name}-reference.md`** — API details and type signatures
+- **`{name}-examples.md`** — Complete, runnable code samples
+
+### Explaining x402 for Python
+
+Understand x402-avm Python package structure, extras installation ([avm], [fastapi], [flask], [httpx], [requests], [all]), signer protocols, async vs sync variants, and algosdk encoding boundaries.
+
+- [explain-algorand-x402-python.md](./references/explain-algorand-x402-python.md) — Package ecosystem explanation
+- [explain-algorand-x402-python-reference.md](./references/explain-algorand-x402-python-reference.md) — API reference for x402-avm packages
+- [explain-algorand-x402-python-examples.md](./references/explain-algorand-x402-python-examples.md) — Python pattern examples
+
+### Building Clients
+
+Build HTTP clients with httpx (async) or requests (sync) that automatically handle 402 payments. Covers wrapHttpxWithPayment, wrapRequestsWithPayment, ClientAvmSigner for payment signing.
+
+- [create-python-x402-client.md](./references/create-python-x402-client.md) — Client creation guide
+- [create-python-x402-client-reference.md](./references/create-python-x402-client-reference.md) — httpx/requests API reference
+- [create-python-x402-client-examples.md](./references/create-python-x402-client-examples.md) — Client code examples
+
+### Building Servers
+
+Build payment-protected servers with FastAPI (async) or Flask (sync) middleware. Covers route pricing, PaymentMiddlewareASGI, Flask PaymentMiddleware, and multi-network support.
+
+- [create-python-x402-server.md](./references/create-python-x402-server.md) — Server creation guide
+- [create-python-x402-server-reference.md](./references/create-python-x402-server-reference.md) — FastAPI/Flask middleware API reference
+- [create-python-x402-server-examples.md](./references/create-python-x402-server-examples.md) — Server code examples
+
+### Building Facilitators and Bazaar Discovery
+
+Build facilitator services that verify and settle Algorand payments on-chain. Covers FacilitatorAvmSigner protocol, register_exact_avm_facilitator, FastAPI facilitator endpoints (/verify, /settle, /supported), and Bazaar discovery extension for automatic cataloging and indexing of payment-gated APIs (declare_discovery_extension, extract_discovery_info, bazaar_resource_server_extension).
+
+- [create-python-x402-facilitator.md](./references/create-python-x402-facilitator.md) — Facilitator creation guide (includes Bazaar setup in Steps 6-10)
+- [create-python-x402-facilitator-reference.md](./references/create-python-x402-facilitator-reference.md) — Facilitator + Bazaar API reference
+- [create-python-x402-facilitator-examples.md](./references/create-python-x402-facilitator-examples.md) — Facilitator + Bazaar code examples
+
+### Low-Level SDK Usage
+
+Use x402-avm core components and AVM mechanism directly for custom integrations. Covers x402Client, x402ResourceServer, x402Facilitator, AVM signer protocols, constants, utilities, transaction encoding, and fee abstraction.
+
+- [use-python-x402-core-avm.md](./references/use-python-x402-core-avm.md) — Core SDK usage guide
+- [use-python-x402-core-avm-reference.md](./references/use-python-x402-core-avm-reference.md) — Core/AVM API reference
+- [use-python-x402-core-avm-examples.md](./references/use-python-x402-core-avm-examples.md) — Core SDK code examples
+
+## Python Package Quick Reference
+
+| Install Extra | Purpose |
+| ------------- | ------- |
+| `x402-avm[httpx]` | Async HTTP client with automatic 402 payment handling |
+| `x402-avm[requests]` | Sync HTTP client with automatic 402 payment handling |
+| `x402-avm[fastapi]` | FastAPI async payment middleware |
+| `x402-avm[flask]` | Flask sync payment middleware |
+| `x402-avm[avm]` | Core AVM mechanism (signers, transaction builders, constants) |
+| `x402-avm[all]` | All extras combined |
+
+## How to Use This Skill
+
+1. **Start here** to understand which reference you need
+2. **Read the `{name}.md`** file for step-by-step implementation guidance
+3. **Consult `{name}-reference.md`** for API details
+4. **Use `{name}-examples.md`** for complete, runnable code samples