openclaw-arcade-plugin 0.1.0

package/README.md

@@ -0,0 +1,21 @@
+# OpenClaw Arcade Plugin
+
+A programmatic OpenClaw plugin that enables transaction broadcasting and full lifecycle tracking using the **BSV Arcade** infrastructure.
+
+## Key Features
+- **Broadcasting**: Submit raw transaction hex directly to the network via Teranode-optimized API.
+- **Lifecycle Tracking**: Monitor transactions through states like `RECEIVED`, `SEEN`, and `MINED`.
+- **Merkle Proofs**: Retrieve cryptographically valid proofs for mined transactions.
+- **Sovereignty**: Configure your own local Arcade instance for maximum reliability.
+
+## AI Tool: `arcade`
+Agents can use the `arcade` tool to:
+- `broadcast`: Send signed transactions to the BSV blockchain.
+- `status`: Check if a transaction has been mined or rejected.
+- `proof`: Get binary proofs for SPV validation.
+
+## Architecture
+Built with the **OpenClaw Plugin SDK**, this extension interfaces with the Arcade REST API to provide agents with a reliable "mouth" for the blockchain.
+
+## License
+MIT

package/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: arcade
+description: >
+  Submit and track BSV transactions. Use for broadcasting raw transaction hex,
+  checking the status of a payment (SEEN, MINED), or retrieving Merkle proofs.
+metadata: '{"openclaw": {"requires": {"bins": ["node"]}}}'
+---
+
+## Tool Actions
+
+| Action | Description |
+|--------|-------------|
+| `broadcast` | Submit a raw transaction hex to the network |
+| `status` | Check the current state of a transaction ID (RECEIVED, SEEN, MINED) |
+| `proof` | Retrieve the Merkle proof for a mined transaction |
+| `config` | Show current broadcaster URL and network |
+
+## Usage Guidance
+
+### Broadcasting Payments
+When you have built and signed a transaction (e.g., using `simplesv` or `overlay`), use `arcade` to send it to the network.
+
+```javascript
+arcade({
+  action: "broadcast",
+  txhex: "01000000..."
+})
+```
+
+### Tracking Confirmation
+If a task requires proof of payment, use `status` to monitor the transaction until it reaches the `MINED` state.
+
+```javascript
+arcade({
+  action: "status",
+  txid: "a1b2c3d4..."
+})
+```
+
+### Generating Proofs
+Use `proof` to get the binary Merkle proof needed for BEEF construction or SPV validation.
+
+## Etiquette
+Broadcasting is the final step of any on-chain operation. Only broadcast once you are certain the transaction is complete and signed.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * OpenClaw Arcade Plugin
+ * Transaction broadcasting and lifecycle tracking via BSV Arcade.
+ */
+export default function register(api: any): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAmFxC"}

package/dist/index.js

@@ -0,0 +1,88 @@
+/**
+ * OpenClaw Arcade Plugin
+ * Transaction broadcasting and lifecycle tracking via BSV Arcade.
+ */
+export default function register(api) {
+    const entries = api.getConfig?.()?.plugins?.entries || {};
+    const entry = entries['openclaw-arcade']
+        || entries['openclaw-arcade-plugin']
+        || entries['bsv-arcade']
+        || {};
+    const pluginConfig = { ...entry, ...(entry.config || {}), ...(api.config || {}) };
+    const arcadeUrl = (pluginConfig.arcadeUrl || 'https://arcade.bsv.direct').replace(/\/$/, '');
+    const network = pluginConfig.network || 'mainnet';
+    api.logger.info(`[arcade] Initializing Arcade Plugin (network: ${network}, host: ${arcadeUrl})`);
+    // Register the arcade tool
+    api.registerTool({
+        name: "arcade",
+        description: "Submit and track BSV transactions with full lifecycle visibility",
+        parameters: {
+            type: "object",
+            properties: {
+                action: {
+                    type: "string",
+                    enum: ["broadcast", "status", "proof", "config"],
+                    description: "Action to perform"
+                },
+                txhex: {
+                    type: "string",
+                    description: "Hex-encoded raw transaction to broadcast"
+                },
+                txid: {
+                    type: "string",
+                    description: "Transaction ID to track or fetch proof for"
+                }
+            },
+            required: ["action"]
+        },
+        async execute(_id, params) {
+            try {
+                const { action, txhex, txid } = params;
+                switch (action) {
+                    case "broadcast":
+                        if (!txhex)
+                            throw new Error("txhex is required for broadcast");
+                        const bResp = await fetch(`${arcadeUrl}/v1/tx`, {
+                            method: 'POST',
+                            headers: { 'Content-Type': 'application/json' },
+                            body: JSON.stringify({ rawTx: txhex })
+                        });
+                        const bData = await bResp.json();
+                        if (!bResp.ok)
+                            throw new Error(`Broadcast failed: ${JSON.stringify(bData)}`);
+                        return { content: [{ type: "text", text: `Transaction broadcasted! TXID: ${bData.txid}\nStatus: ${bData.txStatus}` }] };
+                    case "status":
+                        if (!txid)
+                            throw new Error("txid is required for status check");
+                        const sResp = await fetch(`${arcadeUrl}/v1/tx/${txid}`);
+                        const sData = await sResp.json();
+                        if (!sResp.ok)
+                            throw new Error(`Status check failed: ${JSON.stringify(sData)}`);
+                        return { content: [{ type: "text", text: `Transaction ${txid}:\nStatus: ${sData.txStatus}\nBlock: ${sData.blockHeight || 'Pending'}` }] };
+                    case "proof":
+                        if (!txid)
+                            throw new Error("txid is required for proof retrieval");
+                        const pResp = await fetch(`${arcadeUrl}/v1/tx/${txid}/proof`);
+                        if (!pResp.ok)
+                            throw new Error(`Proof retrieval failed: ${pResp.status}`);
+                        const pData = await pResp.arrayBuffer();
+                        const base64Proof = Buffer.from(pData).toString('base64');
+                        return { content: [{ type: "text", text: `Merkle Proof (Base64): ${base64Proof}` }] };
+                    case "config":
+                        return { content: [{ type: "text", text: `Arcade Configuration:\nURL: ${arcadeUrl}\nNetwork: ${network}` }] };
+                    default:
+                        throw new Error(`Unknown action: ${action}`);
+                }
+            }
+            catch (error) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: ${error.message || String(error)}`
+                        }]
+                };
+            }
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAQ;IACvC,MAAM,OAAO,GAAG,GAAG,CAAC,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,IAAI,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,OAAO,CAAC,iBAAiB,CAAC;WACnC,OAAO,CAAC,wBAAwB,CAAC;WACjC,OAAO,CAAC,YAAY,CAAC;WACrB,EAAE,CAAC;IAER,MAAM,YAAY,GAAG,EAAE,GAAG,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,EAAE,CAAC;IAClF,MAAM,SAAS,GAAG,CAAC,YAAY,CAAC,SAAS,IAAI,2BAA2B,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAC7F,MAAM,OAAO,GAAG,YAAY,CAAC,OAAO,IAAI,SAAS,CAAC;IAElD,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,iDAAiD,OAAO,WAAW,SAAS,GAAG,CAAC,CAAC;IAEjG,2BAA2B;IAC3B,GAAG,CAAC,YAAY,CAAC;QACf,IAAI,EAAE,QAAQ;QACd,WAAW,EAAE,kEAAkE;QAC/E,UAAU,EAAE;YACV,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE;gBACV,MAAM,EAAE;oBACN,IAAI,EAAE,QAAQ;oBACd,IAAI,EAAE,CAAC,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,CAAC;oBAChD,WAAW,EAAE,mBAAmB;iBACjC;gBACD,KAAK,EAAE;oBACL,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,0CAA0C;iBACxD;gBACD,IAAI,EAAE;oBACJ,IAAI,EAAE,QAAQ;oBACd,WAAW,EAAE,4CAA4C;iBAC1D;aACF;YACD,QAAQ,EAAE,CAAC,QAAQ,CAAC;SACrB;QACD,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,MAAW;YACpC,IAAI,CAAC;gBACH,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,CAAC;gBAEvC,QAAQ,MAAM,EAAE,CAAC;oBACf,KAAK,WAAW;wBACd,IAAI,CAAC,KAAK;4BAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;wBAC/D,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,GAAG,SAAS,QAAQ,EAAE;4BAC9C,MAAM,EAAE,MAAM;4BACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;4BAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;yBACvC,CAAC,CAAC;wBACH,MAAM,KAAK,GAAQ,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;wBACtC,IAAI,CAAC,KAAK,CAAC,EAAE;4BAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;wBAC7E,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kCAAkC,KAAK,CAAC,IAAI,aAAa,KAAK,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC;oBAE1H,KAAK,QAAQ;wBACX,IAAI,CAAC,IAAI;4BAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;wBAChE,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,GAAG,SAAS,UAAU,IAAI,EAAE,CAAC,CAAC;wBACxD,MAAM,KAAK,GAAQ,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;wBACtC,IAAI,CAAC,KAAK,CAAC,EAAE;4BAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;wBAChF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,eAAe,IAAI,cAAc,KAAK,CAAC,QAAQ,YAAY,KAAK,CAAC,WAAW,IAAI,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC;oBAE5I,KAAK,OAAO;wBACV,IAAI,CAAC,IAAI;4BAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;wBACnE,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,GAAG,SAAS,UAAU,IAAI,QAAQ,CAAC,CAAC;wBAC9D,IAAI,CAAC,KAAK,CAAC,EAAE;4BAAE,MAAM,IAAI,KAAK,CAAC,2BAA2B,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;wBAC1E,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC;wBACxC,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;wBAC1D,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,0BAA0B,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC;oBAExF,KAAK,QAAQ;wBACX,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,+BAA+B,SAAS,cAAc,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;oBAEhH;wBACE,MAAM,IAAI,KAAK,CAAC,mBAAmB,MAAM,EAAE,CAAC,CAAC;gBACjD,CAAC;YACH,CAAC;YAAC,OAAO,KAAU,EAAE,CAAC;gBACpB,OAAO;oBACL,OAAO,EAAE,CAAC;4BACR,IAAI,EAAE,MAAM;4BACZ,IAAI,EAAE,UAAU,KAAK,CAAC,OAAO,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE;yBACjD,CAAC;iBACH,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/index.ts

@@ -0,0 +1,91 @@
+import path from "node:path";
+import os from "node:os";
+
+/**
+ * OpenClaw Arcade Plugin
+ * Transaction broadcasting and lifecycle tracking via BSV Arcade.
+ */
+export default function register(api: any) {
+  const entries = api.getConfig?.()?.plugins?.entries || {};
+  const entry = entries['openclaw-arcade'] 
+    || entries['openclaw-arcade-plugin'] 
+    || entries['bsv-arcade'] 
+    || {};
+    
+  const pluginConfig = { ...entry, ...(entry.config || {}), ...(api.config || {}) };
+  const arcadeUrl = (pluginConfig.arcadeUrl || 'https://arcade.bsv.direct').replace(/\/$/, '');
+  const network = pluginConfig.network || 'mainnet';
+
+  api.logger.info(`[arcade] Initializing Arcade Plugin (network: ${network}, host: ${arcadeUrl})`);
+
+  // Register the arcade tool
+  api.registerTool({
+    name: "arcade",
+    description: "Submit and track BSV transactions with full lifecycle visibility",
+    parameters: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          enum: ["broadcast", "status", "proof", "config"],
+          description: "Action to perform"
+        },
+        txhex: {
+          type: "string",
+          description: "Hex-encoded raw transaction to broadcast"
+        },
+        txid: {
+          type: "string",
+          description: "Transaction ID to track or fetch proof for"
+        }
+      },
+      required: ["action"]
+    },
+    async execute(_id: string, params: any) {
+      try {
+        const { action, txhex, txid } = params;
+
+        switch (action) {
+          case "broadcast":
+            if (!txhex) throw new Error("txhex is required for broadcast");
+            const bResp = await fetch(`${arcadeUrl}/v1/tx`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ rawTx: txhex })
+            });
+            const bData: any = await bResp.json();
+            if (!bResp.ok) throw new Error(`Broadcast failed: ${JSON.stringify(bData)}`);
+            return { content: [{ type: "text", text: `Transaction broadcasted! TXID: ${bData.txid}\nStatus: ${bData.txStatus}` }] };
+
+          case "status":
+            if (!txid) throw new Error("txid is required for status check");
+            const sResp = await fetch(`${arcadeUrl}/v1/tx/${txid}`);
+            const sData: any = await sResp.json();
+            if (!sResp.ok) throw new Error(`Status check failed: ${JSON.stringify(sData)}`);
+            return { content: [{ type: "text", text: `Transaction ${txid}:\nStatus: ${sData.txStatus}\nBlock: ${sData.blockHeight || 'Pending'}` }] };
+
+          case "proof":
+            if (!txid) throw new Error("txid is required for proof retrieval");
+            const pResp = await fetch(`${arcadeUrl}/v1/tx/${txid}/proof`);
+            if (!pResp.ok) throw new Error(`Proof retrieval failed: ${pResp.status}`);
+            const pData = await pResp.arrayBuffer();
+            const base64Proof = Buffer.from(pData).toString('base64');
+            return { content: [{ type: "text", text: `Merkle Proof (Base64): ${base64Proof}` }] };
+
+          case "config":
+            return { content: [{ type: "text", text: `Arcade Configuration:\nURL: ${arcadeUrl}\nNetwork: ${network}` }] };
+
+          default:
+            throw new Error(`Unknown action: ${action}`);
+        }
+      } catch (error: any) {
+        return {
+          content: [{
+            type: "text",
+            text: `Error: ${error.message || String(error)}`
+          }]
+        };
+      }
+    }
+  });
+}

package/openclaw.plugin.json

@@ -0,0 +1,31 @@
+{
+  "id": "openclaw-arcade",
+  "name": "BSV Arcade Broadcaster",
+  "description": "Submit and track BSV transactions with full lifecycle visibility",
+  "version": "0.1.0",
+  "skills": [
+    "./SKILL.md"
+  ],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "arcadeUrl": {
+        "type": "string",
+        "default": "https://arcade.bsv.direct",
+        "description": "Arcade server URL"
+      },
+      "network": {
+        "type": "string",
+        "enum": ["mainnet", "testnet"],
+        "default": "mainnet"
+      }
+    }
+  },
+  "uiHints": {
+    "arcadeUrl": {
+      "label": "Arcade Server URL",
+      "placeholder": "https://arcade.bsv.direct"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "openclaw-arcade-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for transaction broadcasting and lifecycle tracking via BSV Arcade",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "src/",
+    "dist/",
+    "SKILL.md",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint src/**/*.ts",
+    "test": "npx tsx src/**/*.test.ts"
+  },
+  "dependencies": {
+    "@bsv/sdk": "^2.0.13"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^6.0.2",
+    "eslint": "^10.1.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "bsv",
+    "arcade",
+    "broadcast",
+    "transaction",
+    "tracking"
+  ],
+  "author": "Tomás Díaz",
+  "license": "MIT"
+}