@goplausible/openclaw-algorand-plugin 0.5.0

package/skills/algorand-development/references/use-algokit-cli-reference.md

@@ -0,0 +1,228 @@
+# AlgoKit CLI Reference
+
+Complete reference for AlgoKit CLI commands.
+
+## Project Commands
+
+### algokit project run build
+
+Compile contracts and generate artifacts.
+
+```bash
+algokit project run build
+```
+
+**What it does:**
+- Compiles contracts via Puya compiler
+- Generates ARC-56 app specs (`*.arc56.json`)
+- Creates typed client files
+- Outputs to `artifacts/` directory
+
+### algokit project run test
+
+Run the test suite.
+
+```bash
+algokit project run test
+```
+
+**What it does:**
+- Executes tests using Vitest
+- Uses generated clients to interact with contracts
+- Runs against localnet
+
+### algokit project deploy
+
+Deploy contracts to a network.
+
+```bash
+# Deploy to localnet
+algokit project deploy localnet
+```
+
+**Prerequisites:**
+- Localnet must be running
+- Contracts must be built
+
+## LocalNet Commands
+
+### algokit localnet start
+
+Start the local Algorand network.
+
+```bash
+algokit localnet start
+```
+
+**What it does:**
+- Starts Docker containers for Algorand node
+- Provides local development environment
+- Includes KMD for test accounts
+
+### algokit localnet stop
+
+Stop the local network.
+
+```bash
+algokit localnet stop
+```
+
+### algokit localnet reset
+
+Reset the network state.
+
+```bash
+algokit localnet reset
+```
+
+**Use when:**
+- Need a clean slate
+- State is corrupted
+- Want to restart from genesis
+
+### algokit localnet status
+
+Check network status.
+
+```bash
+algokit localnet status
+```
+
+## Init Commands
+
+### algokit init
+
+Initialize a new project.
+
+```bash
+# TypeScript with Production preset
+algokit init -n my-project -t typescript --answer preset_name production --defaults
+
+# Python with Production preset
+algokit init -n my-project -t python --answer preset_name production --defaults
+```
+
+**Options:**
+
+| Flag | Description |
+|------|-------------|
+| `-n, --name` | Project name |
+| `-t, --template` | Template: `typescript` or `python` |
+| `--answer` | Answer template prompts |
+| `--defaults` | Accept all defaults |
+| `--no-git` | Skip git initialization |
+| `--no-bootstrap` | Skip dependency installation |
+
+## Project Configuration
+
+### .algokit.toml
+
+The `.algokit.toml` file configures project behavior:
+
+```toml
+[project]
+type = "contract"
+name = "my-project"
+artifacts = "smart_contracts/artifacts"
+
+[project.run]
+build = "npm run build"
+test = "npm run test"
+
+[project.deploy]
+command = "npm run deploy:ci"
+environment_secrets = ["DEPLOYER_MNEMONIC"]
+
+[project.deploy.localnet]
+environment_secrets = []
+
+[project.deploy.testnet]
+environment_secrets = ["DEPLOYER_MNEMONIC"]
+```
+
+### Environment Files
+
+Environment variables can be set in `.env` files:
+
+- `.env` — Default values for all environments
+- `.env.localnet` — LocalNet-specific overrides
+- `.env.testnet` — TestNet-specific values
+- `.env.mainnet` — MainNet-specific values
+
+```bash
+# .env.testnet
+ALGOD_SERVER=https://testnet-api.algonode.cloud
+ALGOD_PORT=443
+ALGOD_TOKEN=
+DEPLOYER_MNEMONIC="word1 word2 ..."
+```
+
+The `algokit project deploy` command automatically loads the appropriate `.env.{network}` file.
+
+### Deploy Command Flags
+
+```bash
+# Deploy with specific deployer account
+algokit project deploy testnet --deployer "DEPLOYER_NAME"
+
+# Deploy with custom dispenser (for funding)
+algokit project deploy testnet --dispenser "DISPENSER_NAME"
+```
+
+## Build Artifacts
+
+After `algokit project run build`:
+
+```
+smart_contracts/
+└── artifacts/
+    └── <ContractName>/
+        ├── <ContractName>.arc56.json    # ARC-56 app spec
+        ├── <ContractName>.approval.teal  # Approval program
+        ├── <ContractName>.clear.teal     # Clear program
+        └── <ContractName>Client.ts       # Typed client
+```
+
+## Common Workflows
+
+### Development Cycle
+
+```bash
+# 1. Write/edit contract code
+# 2. Build
+algokit project run build
+
+# 3. Write/edit tests
+# 4. Run tests
+algokit project run test
+
+# 5. Repeat until passing
+```
+
+### Deployment Workflow
+
+```bash
+# 1. Start localnet
+algokit localnet start
+
+# 2. Build contracts
+algokit project run build
+
+# 3. Deploy
+algokit project deploy localnet
+```
+
+### Clean Start
+
+```bash
+# Reset everything
+algokit localnet reset
+algokit project run build
+algokit project run test
+```
+
+## External Documentation
+
+- [AlgoKit CLI Documentation](https://dev.algorand.co/algokit/cli/)
+- [AlgoKit Project Commands](https://dev.algorand.co/reference/algokit-cli/#project)
+- [AlgoKit LocalNet](https://dev.algorand.co/reference/algokit-cli/#localnet)

package/skills/algorand-development/references/use-algokit-cli.md

@@ -0,0 +1,64 @@
+
+# AlgoKit Commands
+
+Standard commands for Algorand development with AlgoKit CLI.
+
+## Overview / Core Workflow
+
+1. Write contract code
+2. Build: `algokit project run build`
+3. Write tests using generated clients
+4. Test: `algokit project run test`
+5. Deploy: `algokit project deploy localnet`
+
+## How to proceed
+
+1. **Build contracts:**
+   ```bash
+   algokit project run build
+   ```
+   This compiles contracts via Puya, generates ARC56 specs, and creates typed clients.
+
+2. **Run tests:**
+   ```bash
+   algokit project run test
+   ```
+   Executes the test suite using Vitest.
+
+3. **Start localnet (if needed):**
+   ```bash
+   algokit localnet start
+   ```
+
+4. **Deploy to localnet:**
+   ```bash
+   algokit project deploy localnet
+   ```
+
+5. **Check build artifacts:**
+   - `artifacts/` — Compiled contracts, ARC56 specs
+   - Generated client files for TypeScript/Python
+
+## Important Rules / Guidelines
+
+- **Always build before testing** — Tests use generated clients
+- **Only deploy when explicitly requested** — Don't auto-deploy
+- **Check localnet status** before deployment operations
+- **Reset localnet** if you need a clean state
+
+## Common Variations / Edge Cases
+
+| Scenario | Command |
+|----------|---------|
+| Start local network | `algokit localnet start` |
+| Stop local network | `algokit localnet stop` |
+| Reset network state | `algokit localnet reset` |
+| Check network status | `algokit localnet status` |
+| Build fails | Check Puya compiler errors, fix contract code |
+| Tests fail | Check test assertions, fix contract or test code |
+
+## References / Further Reading
+
+- [Full CLI Reference](./use-algokit-cli-reference.md)
+- [AlgoKit CLI Documentation](https://dev.algorand.co/algokit/cli/)
+- [AlgoKit Project Commands](https://dev.algorand.co/reference/algokit-cli/#project)

package/skills/algorand-interaction/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: algorand-interaction
+description: Interact with Algorand blockchain via the Algorand MCP server — wallet operations, ALGO/ASA transactions, smart contracts, account info, NFD lookups, atomic groups, Tinyman swaps, TEAL compilation, knowledge base. Use when user asks about Algorand wallet, balances, sending ALGO or tokens, asset opt-in, transactions, NFD names, DEX swaps, smart contracts, or account details.
+---
+
+# Algorand MCP Interaction
+
+Interact with Algorand blockchain through the Algorand MCP server (99 tools across 11 categories).
+
+## Key Characteristics
+
+- **Secure signing** — use `wallet_*` tools to sign; private keys are never available to you
+- **Multi-network** — supports `mainnet`, `testnet`, and `localnet`
+- **Spending limits** — per-transaction (`allowance`) and daily (`dailyAllowance`) limits enforced by wallet
+
+## mcporter Syntax (Critical)
+
+When calling Algorand MCP tools via mcporter, use the correct syntax:
+
+**Correct:**
+```bash
+mcporter call algorand-mcp.tool_name --args '{"param": "value", "network": "testnet"}'
+```
+
+**Also correct (flag-style):**
+```bash
+mcporter call algorand-mcp.tool_name param=value network=testnet
+```
+
+**Wrong — args not sent properly:**
+```bash
+mcporter call algorand-mcp tool_name '{"param": "value"}'  # Space instead of dot, missing --args
+```
+
+Key points:
+- Use `server.tool` (dot notation), NOT `server tool` (space)
+- Use `--args '{"json"}'` for JSON payloads
+- Or use `param=value` / `param:value` flag syntax
+
+## Session Start Checklist
+
+**At EVERY session start:**
+
+1. **Check wallet**: `wallet_get_info` with target `network` — verify an account exists and is active
+2. **If no accounts**: Guide user to create one with `wallet_add_account` (sets nickname and spending limits)
+3. **If needs funding**: Generate ARC-26 QR with `generate_algorand_uri` or direct to testnet faucet: https://lora.algokit.io/testnet/fund
+4. **If needs USDC funding**: Generate ARC-26 QR with `generate_algorand_uri` or direct to testnet faucet: https://faucet.circle.com/
+5. **Confirm network**: Always confirm which network (`mainnet`, `testnet`, `localnet`) before transactions
+
+## Network Selection
+
+Every tool that touches the blockchain accepts a `network` parameter:
+
+| Value | Description |
+|-------|-------------|
+| `mainnet` | Algorand mainnet (default) — **real value, exercise caution** |
+| `testnet` | Algorand testnet — safe for development |
+| `localnet` | Local dev network (requires `ALGORAND_LOCALNET_URL` env var) |
+
+Default to `testnet` during development.
+
+## Pre-Transaction Validation
+
+Before ANY transaction:
+
+1. **MBR Check**: Account needs 0.1 ALGO base + 0.1 per asset/app opt-in
+2. **Asset Opt-In**: Verify with `api_algod_get_account_asset_info` before ASA transfers
+3. **Fees**: Every txn costs 0.001 ALGO (1,000 microAlgos) minimum
+4. **Balance Check**: Fetch current balance with `wallet_get_info` or `api_algod_get_account_info`
+5. **Spending Limits**: Wallet enforces per-transaction and daily limits
+6. **Order**: Fund account with ALGO first, then asset transactions
+
+## Common Mainnet Assets
+
+| Asset | ASA ID | Decimals |
+|-------|--------|----------|
+| ALGO | native | 6 |
+| USDC | 31566704 | 6 |
+| USDT | 312769 | 6 |
+| goETH | 386192725 | 8 |
+| goBTC | 386195940 | 8 |
+
+> Always verify asset IDs on-chain — scam tokens use similar names.
+
+## Amounts and Decimals
+
+| Asset | Unit | 1 Whole Token = |
+|-------|------|-----------------|
+| ALGO | microAlgos | 1,000,000 |
+| USDC (ASA 31566704) | micro-units | 1,000,000 (6 decimals) |
+| Custom ASAs | base units | Depends on `decimals` field |
+
+Always check asset's `decimals` field with `api_algod_get_asset_by_id` before computing amounts.
+
+## Transaction Types
+
+- **pay**: ALGO transfers → `make_payment_txn`
+- **axfer**: Asset transfers, opt-in, clawback → `make_asset_transfer_txn`
+- **acfg**: Asset create/configure/destroy → `make_asset_create_txn`, `make_asset_config_txn`, `make_asset_destroy_txn`
+- **afrz**: Asset freeze/unfreeze → `make_asset_freeze_txn`
+- **appl**: Smart contract calls → `make_app_create_txn`, `make_app_call_txn`, `make_app_update_txn`, `make_app_delete_txn`, `make_app_optin_txn`, `make_app_closeout_txn`, `make_app_clear_txn`
+- **keyreg**: Consensus key registration → `make_keyreg_txn`
+
+## Wallet Transaction Workflow (Recommended)
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| 1 | `wallet_get_info` | Verify active account, check balance |
+| 2 | Query tools | Get blockchain data (account info, asset info, etc.) |
+| 3 | `make_*_txn` | Build the transaction |
+| 4 | `wallet_sign_transaction` | Sign with active wallet account (enforces limits) |
+| 5 | `send_raw_transaction` | Submit signed transaction to network |
+| 6 | Query tools | Verify result on-chain |
+
+### One-Step Asset Opt-In
+
+For asset opt-ins, use the shortcut:
+```
+wallet_optin_asset { assetId: 31566704, network: "testnet" }
+```
+
+## External Key Transaction Workflow
+
+When the user provides their own secret key (not using the wallet):
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| 1 | `make_*_txn` | Build the transaction |
+| 2 | `sign_transaction` | Sign with provided secret key hex |
+| 3 | `send_raw_transaction` | Submit signed transaction |
+
+## Atomic Group Transaction Workflow
+
+For atomic (all-or-nothing) multi-transaction groups:
+
+| Step | Tool | Purpose |
+|------|------|---------|
+| 1 | `make_*_txn` (multiple) | Build each transaction |
+| 2 | `assign_group_id` | Assign group ID to all transactions |
+| 3 | `wallet_sign_transaction_group` | Sign all transactions in group with wallet |
+| 4 | `send_raw_transaction` | Submit all signed transactions |
+
+## Tool Categories
+
+**Wallet** (10): `wallet_add_account`, `wallet_remove_account`, `wallet_list_accounts`, `wallet_switch_account`, `wallet_get_info`, `wallet_get_assets`, `wallet_sign_transaction`, `wallet_sign_transaction_group`, `wallet_sign_data`, `wallet_optin_asset`
+
+**Account** (8): `create_account`, `rekey_account`, `mnemonic_to_mdk`, `mdk_to_mnemonic`, `secret_key_to_mnemonic`, `mnemonic_to_secret_key`, `seed_from_mnemonic`, `mnemonic_from_seed`
+
+**Utility** (13): `ping`, `validate_address`, `encode_address`, `decode_address`, `get_application_address`, `bytes_to_bigint`, `bigint_to_bytes`, `encode_uint64`, `decode_uint64`, `verify_bytes`, `sign_bytes`, `encode_obj`, `decode_obj`
+
+**Transaction Building** (16): `make_payment_txn`, `make_keyreg_txn`, `make_asset_create_txn`, `make_asset_config_txn`, `make_asset_destroy_txn`, `make_asset_freeze_txn`, `make_asset_transfer_txn`, `make_app_create_txn`, `make_app_update_txn`, `make_app_delete_txn`, `make_app_optin_txn`, `make_app_closeout_txn`, `make_app_clear_txn`, `make_app_call_txn`, `assign_group_id`, `sign_transaction`
+
+**Algod** (5): `compile_teal`, `disassemble_teal`, `send_raw_transaction`, `simulate_raw_transactions`, `simulate_transactions`
+
+**Algod API** (13): `api_algod_get_account_info`, `api_algod_get_account_application_info`, `api_algod_get_account_asset_info`, `api_algod_get_application_by_id`, `api_algod_get_application_box`, `api_algod_get_application_boxes`, `api_algod_get_asset_by_id`, `api_algod_get_pending_transaction`, `api_algod_get_pending_transactions_by_address`, `api_algod_get_pending_transactions`, `api_algod_get_transaction_params`, `api_algod_get_node_status`, `api_algod_get_node_status_after_block`
+
+**Indexer API** (17): `api_indexer_lookup_account_by_id`, `api_indexer_lookup_account_assets`, `api_indexer_lookup_account_app_local_states`, `api_indexer_lookup_account_created_applications`, `api_indexer_search_for_accounts`, `api_indexer_lookup_applications`, `api_indexer_lookup_application_logs`, `api_indexer_search_for_applications`, `api_indexer_lookup_application_box`, `api_indexer_lookup_application_boxes`, `api_indexer_lookup_asset_by_id`, `api_indexer_lookup_asset_balances`, `api_indexer_lookup_asset_transactions`, `api_indexer_search_for_assets`, `api_indexer_lookup_transaction_by_id`, `api_indexer_lookup_account_transactions`, `api_indexer_search_for_transactions`
+
+**NFDomains** (6): `api_nfd_get_nfd`, `api_nfd_get_nfds_for_addresses`, `api_nfd_get_nfd_activity`, `api_nfd_get_nfd_analytics`, `api_nfd_browse_nfds`, `api_nfd_search_nfds`
+
+**Tinyman DEX** (9): `api_tinyman_get_pool`, `api_tinyman_get_pool_analytics`, `api_tinyman_get_pool_creation_quote`, `api_tinyman_get_liquidity_quote`, `api_tinyman_get_remove_liquidity_quote`, `api_tinyman_get_swap_quote`, `api_tinyman_get_asset_optin_quote`, `api_tinyman_get_validator_optin_quote`, `api_tinyman_get_validator_optout_quote`
+
+**ARC-26 URI** (1): `generate_algorand_uri`
+
+**Knowledge Base** (1): `get_knowledge_doc`
+
+## Pagination
+
+API responses are paginated. All API tools accept optional `itemsPerPage` (default 10) and `pageToken` parameters. Pass `pageToken` from a previous response to fetch the next page.
+
+## x402 Payment Workflow for OpenClaw agents
+
+When `x402_fetch` returns HTTP 402 with `PaymentRequirements`, use the atomic group transaction pattern to build the payment:
+
+1. Build fee payer transaction (0-amount from facilitator's `feePayer` address, `fee: 2000`, `flatFee: true` — covers fees for both txns)
+2. Build payment transaction (ALGO or ASA transfer to `payTo`, `fee: 0`, `flatFee: true` — facilitator covers fee)
+3. Group both transactions with `assign_group_id`
+4. Sign only the payment transaction (index 1) with wallet and tool wallet_sign_transaction — leave fee payer unsigned
+5. Encode the unsigned fee payer transaction (index 0) with `encode_unsigned_transaction`
+6. Construct PAYMENT-SIGNATURE JSON payload — **must include `accepted` field** (the exact `accepts[]` entry chosen) — and retry with `x402_fetch`
+
+**Critical**: The `accepted` field is REQUIRED. It must be an exact copy of the `accepts[]` entry you chose to pay with (including all fields: scheme, network, price, payTo, asset, maxAmountRequired, extra, etc.). Without it, the server cannot match your payment and will reject with 402.
+
+Map CAIP-2 network identifiers from `accepts[].network` to `testnet` or `mainnet`.
+
+See [references/examples-algorand-mcp.md](references/examples-algorand-mcp.md) for the full step-by-step workflow.
+
+## References
+
+For detailed tool documentation:
+- **Tool Reference**: See [references/algorand-mcp.md](references/algorand-mcp.md)
+
+For workflow examples (including x402 payment):
+- **Examples**: See [references/examples-algorand-mcp.md](references/examples-algorand-mcp.md)
+
+## NFD Important Note
+
+When using NFD (`.algo` names), always use the `depositAccount` field from the NFD response for transactions, NOT other address fields.
+
+## Security
+
+- **Mainnet = real value** — always confirm with user before mainnet transactions
+- Never log, display, or store mnemonics or secret keys — use `wallet_*` tools for signing
+- Verify recipient addresses with `validate_address` — transactions are irreversible
+- Verify asset IDs on-chain — scam tokens use similar names
+- Respect wallet spending limits — if rejected, inform user rather than bypassing
+
+## Links
+
+- GoPlausible: https://goplausible.com
+- Algorand: https://algorand.co
+- Algorand x402: https://x402.goplausible.xyz
+- Algorand x402 test endpoints: https://example.x402.goplausible.xyz/
+- Algorand x402 Facilitator: https://facilitator.goplausible.xyz
+- Testnet Faucet: https://lora.algokit.io/testnet/fund
+- Testnet USDC Faucet: https://faucet.circle.com/
+- Algorand Developer Docs: https://dev.algorand.co/
+- Algorand Developer Docs Github : https://github.com/algorandfoundation/devportal
+- Algorand Developer Examples Github : https://github.com/algorandfoundation/devportal-code-examples
+- [GoPlausible x402-avm Documentation and Example code](https://github.com/GoPlausible/.github/blob/main/profile/algorand-x402-documentation/README.md)
+- [GoPlausible x402-avm Examples template Projects](https://github.com/GoPlausible/x402-avm/tree/branch-v2-algorand-publish/examples/)
+- [CAIP-2 Specification](https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md)
+- [Coinbase x402 Protocol](https://github.com/coinbase/x402)