@goplausible/openclaw-algorand-plugin 2.0.1 → 2.0.3

package/README.md

@@ -4,50 +4,81 @@
 
 ## Features
 
-- **Local MCP Server**: Bundled `algorand-mcp` (107 tools) — wallet, transactions, smart contracts, TEAL, indexer, DEX, NFD, Haystack Router, Alpha Arcade, knowledge base
+- **Bundled Algorand MCP Server**: `@goplausible/algorand-mcp` (pinned to `^4.2.2`, 107 tools) — wallet, transactions, smart contracts, TEAL, indexer, DEX, NFD, Haystack Router, Alpha Arcade, knowledge base
 - **x402 Payment Protocol**: Built-in `x402_fetch` tool for HTTP-native payments on Algorand
-- **Headless Linux Keyring Persistence**: Automatic setup for wallet key persistence on cloud VMs and Docker (survives reboots)
-- **Interactive Setup**: Guided wizard for configuration
-- **Skills Included** (9 skills):
+- **Zero-privilege installation**: First-load init only writes a declarative entry into `~/.mcporter/mcporter.json` and a memory file into the agent workspace — no shell scripts, no system packages, no keyring installation, no `sudo`, no post-install hooks
+- **9 Skills** covering development, interaction, x402, DEX aggregation, and prediction markets:
   - `algorand-development` — AlgoKit CLI, project creation, general workflows
   - `algorand-typescript` — TypeScript smart contracts (PuyaTs)
   - `algorand-python` — Python smart contracts (PuyaPy)
   - `algorand-interaction` — Blockchain interaction via MCP (wallet, transactions, swaps, NFD)
   - `algorand-x402-typescript` — x402 payments in TypeScript
   - `algorand-x402-python` — x402 payments in Python
-  - `algorand-x402-payment` — Runtime x402 payment (agent as client)
   - `haystack-router-development` — DEX aggregator SDK integration
   - `haystack-router-interaction` — Best-price swaps via MCP tools
   - `alpha-arcade-interaction` — Prediction markets interaction
 
 ## Installation
 
+From [ClawHub](https://clawhub.ai):
+
 ```bash
-openclaw plugins install @goplausible/openclaw-algorand-plugin
+clawhub install @goplausible/openclaw-algorand-plugin
 ```
 
-Or install from local path if you are running from source code:
+Or from a local path (source code):
 
 ```bash
 openclaw plugins install ./path/to/openclaw-algorand-plugin
 ```
 
-## Post-Installation Setup
+## Configuration
+
+On first load, the plugin initializes idempotently:
 
-After installing, run these commands:
+- Writes the plugin memory file into your agent workspace (`memory/algorand-plugin.md`)
+- Ensures the workspace `MEMORY.md` contains the Algorand NEVER FORGET block
+- Registers `algorand-mcp` in `~/.mcporter/mcporter.json`
+
+To (re)run the interactive configuration wizard or rewrite the mcporter entry:
 
 ```bash
-# 1. Setup plugin (memory file + mcporter + interactive config)
 openclaw algorand-plugin setup
-
-# 2. Restart the gateway
 openclaw gateway restart
 ```
 
+## What this plugin writes to your system
+
+The plugin performs only **declarative file writes** — no shell scripts, no system packages, no privilege elevation, no keyring installation, no D-Bus/loginctl changes.
+
+| Path | When | Purpose |
+|------|------|---------|
+| `~/.mcporter/mcporter.json` | First load + `setup` | Idempotently adds an `algorand-mcp` entry pointing at the bundled binary. Existing entries for other servers are preserved. |
+| `<agent-workspace>/memory/algorand-plugin.md` | First load + `setup` | Writes the plugin's Algorand routing guide for the agent. |
+| `<agent-workspace>/MEMORY.md` | First load + `setup` | Adds a `## NEVER FORGET` block (or updates its subsections) if not already present. Existing content is preserved. |
+| `<agent-workspace>/.openclaw/openclaw-algorand-plugin.initialized` | First load | Marker file so first-load init is skipped on subsequent gateway starts. |
+| `~/.openclaw/openclaw.json` | When you run `openclaw algorand-plugin setup` and confirm | Persists the plugin config (`enableX402`). |
+
+The plugin does **not**:
+
+- Install OS packages (no `apt`, `brew`, `pacman`, `gnome-keyring`, `libsecret-tools`, `dbus-user-session`).
+- Elevate privileges or require `sudo`.
+- Run shell scripts, `loginctl linger`, or any D-Bus session setup.
+- Read or back up wallet mnemonics — wallet storage is owned entirely by `@goplausible/algorand-mcp`.
+- Register post-install or post-update hooks.
+
+The source is small and self-contained:
+
+- [`index.ts`](./index.ts) — plugin entry, tool + CLI registration
+- [`lib/mcporter.ts`](./lib/mcporter.ts) — mcporter JSON merge
+- [`lib/workspace.ts`](./lib/workspace.ts) — memory file + MEMORY.md merge + plugin config writer
+- [`lib/x402-fetch.ts`](./lib/x402-fetch.ts) — x402 fetch implementation
+- [`setup.ts`](./setup.ts) — interactive config prompt (x402 toggle only)
+
 ## Commands
 
 ```bash
-openclaw algorand-plugin setup       # Initialize + configure plugin (memory, mcporter, options)
+openclaw algorand-plugin setup       # Re-run interactive configuration
 openclaw algorand-plugin status      # Show plugin status (binary, mcporter, config)
 openclaw algorand-plugin mcp-config  # Show MCP config snippet for external coding agents
 ```
@@ -60,6 +91,8 @@ The plugin bundles [`@goplausible/algorand-mcp`](https://www.npmjs.com/package/@
 - **Multi-network**: `mainnet`, `testnet`, `localnet`
 - **Secure wallet**: Per-transaction and daily spending limits, private keys never exposed to agents
 
+Wallet persistence is handled by `algorand-mcp` itself. The plugin does not install, configure, or manage any keyring software — it simply registers the MCP server with mcporter and lets the MCP server own wallet storage.
+
 ## x402 Payment Protocol
 
 When `enableX402` is enabled (default), the plugin registers the `x402_fetch` tool — an HTTP fetch with [x402](https://github.com/coinbase/x402) payment protocol support.
@@ -68,20 +101,9 @@ When `enableX402` is enabled (default), the plugin registers the `x402_fetch` to
 - Agent builds payment using algorand-mcp wallet tools (atomic group with facilitator-sponsored fees)
 - Agent retries with signed `PAYMENT-SIGNATURE` header to complete the payment and access the resource
 
-## Headless Linux (Cloud VMs, Docker)
-
-On headless Linux, the OS keyring defaults to in-memory storage — wallet keys created by `algorand-mcp` are **lost on reboot**. The setup wizard (`openclaw algorand-plugin setup`) automatically detects this and:
-
-1. Installs `gnome-keyring`, `libsecret-tools`, `dbus-user-session`
-2. Enables `loginctl linger` for D-Bus session persistence
-3. Creates a persistent login keyring (auto-unlocked, no password)
-4. Backs up and restores existing wallet mnemonics if upgrading
-
-After setup, wallet keys persist across reboots with no user interaction needed. Agent wallets are hot wallets — keep funds minimal and use QR code top-ups.
+## Plugin Config
 
-## Configuration
-
-Config is stored in `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-algorand-plugin.config`:
+Config lives in `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-algorand-plugin.config`:
 
 ```json
 {
@@ -98,6 +120,10 @@ Config is stored in `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-
 }
 ```
 
+| Key | Default | Description |
+|-----|---------|-------------|
+| `enableX402` | `true` | Enable `x402_fetch` tool and x402 skills |
+
 ## Skills Overview
 
 | Skill | Purpose |
@@ -108,9 +134,15 @@ Config is stored in `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-
 | `algorand-interaction` | MCP-based blockchain interaction (wallet, txns, DEX, NFD, x402) |
 | `algorand-x402-typescript` | x402 payments in TypeScript |
 | `algorand-x402-python` | x402 payments in Python |
-| `haystack-router-development` | Haystack router development |
-| `haystack-router-interaction` | Haystack router interaction |
-| `alpha-arcade-interaction` | Alpha Arcade interaction |
+| `haystack-router-development` | Haystack router SDK integration |
+| `haystack-router-interaction` | Haystack router interaction via MCP |
+| `alpha-arcade-interaction` | Alpha Arcade prediction markets interaction |
+
+## Compatibility
+
+- **OpenClaw gateway**: `>= 2026.3.14`
+- **Plugin API**: `>= 2026.3.14`
+- **Node**: `>= 20`
 
 ## Links
 
@@ -121,6 +153,7 @@ Config is stored in `~/.openclaw/openclaw.json` under `plugins.entries.openclaw-
 - **Algorand x402 test endpoints**: https://example.x402.goplausible.xyz/
 - **Algorand x402 Facilitator**: https://facilitator.goplausible.xyz
 - **OpenClaw**: https://openclaw.ai
+- **ClawHub**: https://clawhub.ai
 
 ## License
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-algorand-plugin",
   "name": "Algorand Integration",
   "description": "Algorand blockchain integration with MCP and skills — by GoPlausible",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "skills": [
     "skills/algorand-development",
     "skills/algorand-typescript",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goplausible/openclaw-algorand-plugin",
-  "version": "2.0.1",
+  "version": "2.0.3",
   "publishConfig": {
     "access": "public"
   },
@@ -23,6 +23,12 @@
   "license": "MIT",
   "type": "module",
   "main": "index.ts",
+  "scripts": {
+    "tag": "git tag -a \"v$npm_package_version\" -m \"v$npm_package_version\" && git push origin \"v$npm_package_version\"",
+    "retag": "git tag -d \"v$npm_package_version\" 2>/dev/null; git push origin \":refs/tags/v$npm_package_version\" 2>/dev/null; git tag -a \"v$npm_package_version\" -m \"v$npm_package_version\" && git push origin \"v$npm_package_version\"",
+    "publish:npm": "npm publish --access public",
+    "publish:clawhub": "clawhub package publish . --family code-plugin --name @goplausible/openclaw-algorand-plugin --display-name 'Algorand Plugin' --version \"$npm_package_version\" --tags latest --source-repo GoPlausible/openclaw-algorand-plugin --source-commit \"$(git rev-parse \"v$npm_package_version\")\" --source-ref \"v$npm_package_version\""
+  },
   "files": [
     "index.ts",
     "setup.ts",
@@ -43,7 +49,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.7.0",
-    "@goplausible/algorand-mcp": "latest"
+    "@goplausible/algorand-mcp": "^4.2.3"
   },
   "peerDependencies": {
     "openclaw": ">=2026.3.14"

package/skills/alpha-arcade-interaction/SKILL.md

@@ -17,7 +17,7 @@ Interact with Alpha Arcade prediction markets via the Alpha Arcade MCP server (1
 
 ## Setup
 
-Alpha Arcade tools are built into the Algorand MCP server. Trading uses the local wallet (OS keychain) — no separate mnemonic needed.
+Alpha Arcade tools are built into the Algorand MCP server. Trading uses the MCP-managed local wallet — no separate mnemonic needed.
 
 | Variable | Required | Description |
 |----------|----------|-------------|