@agentlayer.tech/wallet 0.1.101 → 0.1.103

package/connectors/spec/transaction-intent.schema.json

@@ -0,0 +1,281 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://agent-layer.tech/schemas/connectors/v1/transaction-intent.schema.json",
+  "title": "AgentLayer Connector Transaction Intent v1",
+  "oneOf": [
+    {
+      "$ref": "#/$defs/evmIntent"
+    },
+    {
+      "$ref": "#/$defs/solanaIntent"
+    }
+  ],
+  "$defs": {
+    "uintString": {
+      "type": "string",
+      "pattern": "^(0|[1-9][0-9]*)$",
+      "maxLength": 80
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "evmAddress": {
+      "type": "string",
+      "pattern": "^0x[0-9a-fA-F]{40}$"
+    },
+    "solanaAddress": {
+      "type": "string",
+      "pattern": "^[1-9A-HJ-NP-Za-km-z]{32,44}$"
+    },
+    "expectedEffect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "asset", "direction", "amount"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["asset", "debt", "position", "protocol_fee", "network_fee"]
+        },
+        "asset": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "direction": {
+          "type": "string",
+          "enum": ["debit", "credit", "increase", "decrease"]
+        },
+        "amount": {
+          "$ref": "#/$defs/uintString"
+        },
+        "recipient": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128
+        },
+        "description": {
+          "type": "string",
+          "maxLength": 300
+        }
+      }
+    },
+    "baseIntent": {
+      "type": "object",
+      "required": [
+        "protocol_version",
+        "connector_id",
+        "connector_version",
+        "artifact_digest",
+        "tool",
+        "quote_fingerprint",
+        "expires_at",
+        "expected_effects"
+      ],
+      "properties": {
+        "protocol_version": {
+          "const": 1
+        },
+        "connector_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(?:[._-][a-z0-9]+)+$",
+          "maxLength": 128
+        },
+        "connector_version": {
+          "type": "string",
+          "maxLength": 64
+        },
+        "artifact_digest": {
+          "$ref": "#/$defs/digest"
+        },
+        "tool": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9_]{1,63}$"
+        },
+        "quote_fingerprint": {
+          "$ref": "#/$defs/digest"
+        },
+        "expires_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "expected_effects": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/$defs/expectedEffect"
+          }
+        }
+      }
+    },
+    "evmCall": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["to", "data", "value_wei"],
+      "properties": {
+        "to": {
+          "$ref": "#/$defs/evmAddress"
+        },
+        "data": {
+          "type": "string",
+          "pattern": "^0x(?:[0-9a-fA-F]{2})*$",
+          "maxLength": 262146
+        },
+        "value_wei": {
+          "$ref": "#/$defs/uintString"
+        },
+        "purpose": {
+          "type": "string",
+          "maxLength": 200
+        }
+      }
+    },
+    "evmApproval": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["token", "spender", "amount_raw"],
+      "properties": {
+        "token": {
+          "$ref": "#/$defs/evmAddress"
+        },
+        "spender": {
+          "$ref": "#/$defs/evmAddress"
+        },
+        "amount_raw": {
+          "$ref": "#/$defs/uintString"
+        }
+      }
+    },
+    "evmIntent": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/baseIntent"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "protocol_version",
+            "connector_id",
+            "connector_version",
+            "artifact_digest",
+            "tool",
+            "quote_fingerprint",
+            "expires_at",
+            "expected_effects",
+            "kind",
+            "chain_id",
+            "from",
+            "calls",
+            "approvals"
+          ],
+          "properties": {
+            "protocol_version": true,
+            "connector_id": true,
+            "connector_version": true,
+            "artifact_digest": true,
+            "tool": true,
+            "quote_fingerprint": true,
+            "expires_at": true,
+            "expected_effects": true,
+            "kind": {
+              "const": "evm_transaction_intent"
+            },
+            "chain_id": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "from": {
+              "$ref": "#/$defs/evmAddress"
+            },
+            "calls": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 16,
+              "items": {
+                "$ref": "#/$defs/evmCall"
+              }
+            },
+            "approvals": {
+              "type": "array",
+              "maxItems": 16,
+              "items": {
+                "$ref": "#/$defs/evmApproval"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "solanaIntent": {
+      "allOf": [
+        {
+          "$ref": "#/$defs/baseIntent"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "protocol_version",
+            "connector_id",
+            "connector_version",
+            "artifact_digest",
+            "tool",
+            "quote_fingerprint",
+            "expires_at",
+            "expected_effects",
+            "kind",
+            "network",
+            "fee_payer",
+            "transaction_base64",
+            "program_ids"
+          ],
+          "properties": {
+            "protocol_version": true,
+            "connector_id": true,
+            "connector_version": true,
+            "artifact_digest": true,
+            "tool": true,
+            "quote_fingerprint": true,
+            "expires_at": true,
+            "expected_effects": true,
+            "kind": {
+              "const": "solana_transaction_intent"
+            },
+            "network": {
+              "type": "string",
+              "enum": ["mainnet", "devnet", "testnet"]
+            },
+            "fee_payer": {
+              "$ref": "#/$defs/solanaAddress"
+            },
+            "transaction_base64": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 524288,
+              "contentEncoding": "base64"
+            },
+            "program_ids": {
+              "type": "array",
+              "minItems": 1,
+              "maxItems": 64,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/solanaAddress"
+              }
+            },
+            "required_accounts": {
+              "type": "array",
+              "maxItems": 128,
+              "uniqueItems": true,
+              "items": {
+                "$ref": "#/$defs/solanaAddress"
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}

package/connectors/templates/read-only/.env.example

@@ -0,0 +1 @@
+UPSTREAM_API_URL=https://api.example.com

package/connectors/templates/read-only/Dockerfile

@@ -0,0 +1,11 @@
+FROM node:24-alpine AS build
+WORKDIR /app/connectors
+COPY connectors/ /app/connectors/
+RUN npm ci && npm run build --workspace @agentlayer.tech/read-only-connector-template
+
+FROM node:24-alpine
+ENV NODE_ENV=production
+WORKDIR /app/connectors
+COPY --from=build /app /app
+USER node
+CMD ["npm", "run", "start", "--workspace", "@agentlayer.tech/read-only-connector-template"]

package/connectors/templates/read-only/README.md

@@ -0,0 +1,33 @@
+# AgentLayer read-only connector template
+
+This is a minimal TypeScript connector suitable for an isolated Railway
+service. It exposes `GET /healthz` and `POST /invoke` through the AgentLayer
+Connector SDK.
+
+## Customize
+
+1. Change the connector identity, publisher, deployment URL, allowed upstream
+   hosts, tools, and schemas in `connector.json`.
+2. Replace the example handler in `src/connector.ts`.
+3. Keep every community tool read-only and keep `transaction_intents: false`.
+4. Add tests for normalization and every declared output shape.
+
+From the repository's `connectors/` directory:
+
+```bash
+npm install
+npm run check --workspace @agentlayer.tech/read-only-connector-template
+npm run start --workspace @agentlayer.tech/read-only-connector-template
+```
+
+After deployment, replace `transport.url`, run the conformance suite, then
+install the manifest locally with:
+
+```bash
+wallet connectors inspect ./connector.json
+wallet connectors install ./connector.json --enable --yes
+```
+
+Never put upstream credentials in `connector.json`. Configure them as Railway
+service variables and keep `permissions.network_hosts` limited to exact public
+HTTPS hosts.

package/connectors/templates/read-only/conformance.json

@@ -0,0 +1,11 @@
+{
+  "schema_version": 1,
+  "tools": {
+    "get_pools": {
+      "arguments": {
+        "chain": "base",
+        "limit": 10
+      }
+    }
+  }
+}

package/connectors/templates/read-only/connector.json

@@ -0,0 +1,64 @@
+{
+  "schema_version": 1,
+  "id": "com.example.defi-markets",
+  "name": "Example DeFi Markets",
+  "version": "1.0.0",
+  "publisher": {
+    "id": "example",
+    "name": "Example Publisher",
+    "url": "https://example.com"
+  },
+  "agentlayer": {
+    "protocol_version": 1,
+    "runtime_range": ">=0.1.101"
+  },
+  "trust": "community_read_only",
+  "transport": {
+    "type": "https",
+    "url": "https://replace-me.up.railway.app",
+    "timeout_ms": 10000
+  },
+  "permissions": {
+    "wallet_address": false,
+    "transaction_intents": false,
+    "network_hosts": ["api.example.com"]
+  },
+  "tools": [
+    {
+      "name": "get_pools",
+      "description": "List public DeFi pools from the configured upstream API.",
+      "read_only": true,
+      "risk_level": "low",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "chain": { "type": "string", "minLength": 1, "maxLength": 64 },
+          "limit": { "type": "integer", "minimum": 1, "maximum": 50 }
+        },
+        "required": ["chain"],
+        "additionalProperties": false
+      },
+      "output_schema": {
+        "type": "object",
+        "properties": {
+          "pools": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": { "type": "string" },
+                "symbol": { "type": "string" },
+                "apy": { "type": ["number", "null"] },
+                "tvl_usd": { "type": ["number", "null"] }
+              },
+              "required": ["id", "symbol", "apy", "tvl_usd"],
+              "additionalProperties": false
+            }
+          }
+        },
+        "required": ["pools"],
+        "additionalProperties": false
+      }
+    }
+  ]
+}

package/connectors/templates/read-only/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@agentlayer.tech/read-only-connector-template",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/server.js",
+    "check": "npm run build && node --test test/*.test.mjs"
+  },
+  "dependencies": {
+    "@agentlayer.tech/connector-sdk": "0.1.0-beta.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^7.0.2"
+  }
+}

package/connectors/templates/read-only/railway.toml

@@ -0,0 +1,9 @@
+[build]
+builder = "DOCKERFILE"
+dockerfilePath = "connectors/templates/read-only/Dockerfile"
+
+[deploy]
+healthcheckPath = "/healthz"
+healthcheckTimeout = 10
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 3

package/connectors/templates/read-only/src/connector.ts

@@ -0,0 +1,61 @@
+import { readFileSync } from "node:fs";
+
+import {
+  defineReadOnlyConnector,
+  type ConnectorManifest,
+  type JsonObject,
+} from "@agentlayer.tech/connector-sdk";
+
+const manifest = JSON.parse(
+  readFileSync(new URL("../connector.json", import.meta.url), "utf8")
+) as ConnectorManifest;
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function normalizePool(value: unknown): JsonObject | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const pool = value as Record<string, unknown>;
+  if (typeof pool.id !== "string" || typeof pool.symbol !== "string") return null;
+  return {
+    id: pool.id,
+    symbol: pool.symbol,
+    apy: numberOrNull(pool.apy),
+    tvl_usd: numberOrNull(pool.tvl_usd),
+  };
+}
+
+async function getPools(arguments_: JsonObject): Promise<JsonObject> {
+  const rawBaseUrl = process.env.UPSTREAM_API_URL ?? "https://api.example.com";
+  const baseUrl = new URL(rawBaseUrl);
+  if (
+    baseUrl.protocol !== "https:" ||
+    !manifest.permissions.network_hosts.includes(baseUrl.hostname)
+  ) {
+    throw new Error("UPSTREAM_API_URL must be HTTPS and declared in permissions.network_hosts.");
+  }
+  const url = new URL("/v1/pools", baseUrl);
+  url.searchParams.set("chain", String(arguments_.chain));
+  url.searchParams.set("limit", String(arguments_.limit ?? 20));
+  const response = await fetch(url, {
+    headers: { accept: "application/json" },
+    redirect: "error",
+    signal: AbortSignal.timeout(5000),
+  });
+  if (!response.ok) throw new Error(`Upstream returned HTTP ${response.status}.`);
+  const payload: unknown = await response.json();
+  const rawPools =
+    payload && typeof payload === "object" && !Array.isArray(payload)
+      ? (payload as Record<string, unknown>).pools
+      : null;
+  if (!Array.isArray(rawPools)) throw new Error("Upstream response is missing pools.");
+  const limit = Number(arguments_.limit ?? 20);
+  return { pools: rawPools.map(normalizePool).filter((pool) => pool !== null).slice(0, limit) };
+}
+
+export const connector = defineReadOnlyConnector({
+  manifest,
+  handlers: { get_pools: getPools },
+  responseTtlSeconds: 60,
+});

package/connectors/templates/read-only/src/server.ts

@@ -0,0 +1,14 @@
+import { startConnectorServer } from "@agentlayer.tech/connector-sdk";
+
+import { connector } from "./connector.js";
+
+const server = await startConnectorServer(connector);
+const address = server.address();
+console.log(
+  JSON.stringify({
+    event: "connector_started",
+    connector_id: connector.manifest.id,
+    connector_version: connector.manifest.version,
+    address,
+  })
+);

package/connectors/templates/read-only/test/connector.test.mjs

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { connector } from "../dist/connector.js";
+
+test("normalizes upstream data into the declared output schema", async () => {
+  const previousFetch = globalThis.fetch;
+  const previousUrl = process.env.UPSTREAM_API_URL;
+  process.env.UPSTREAM_API_URL = "https://api.example.com";
+  globalThis.fetch = async (url, options) => {
+    assert.equal(url.hostname, "api.example.com");
+    assert.equal(url.searchParams.get("chain"), "base");
+    assert.equal(options.redirect, "error");
+    return new Response(
+      JSON.stringify({
+        pools: [
+          { id: "pool-1", symbol: "USDC", apy: 5.2, tvl_usd: 1000000, ignored: true },
+          { id: 123, symbol: "invalid" },
+        ],
+      }),
+      { status: 200, headers: { "content-type": "application/json" } }
+    );
+  };
+  try {
+    const result = await connector.invoke({
+      protocol_version: 1,
+      request_id: "template-request-1",
+      connector: { id: connector.manifest.id, version: connector.manifest.version },
+      tool: "get_pools",
+      arguments: { chain: "base", limit: 10 },
+      context: { chain: "evm", network: "base" },
+    });
+    assert.deepEqual(result.result, {
+      pools: [{ id: "pool-1", symbol: "USDC", apy: 5.2, tvl_usd: 1000000 }],
+    });
+  } finally {
+    globalThis.fetch = previousFetch;
+    if (previousUrl === undefined) delete process.env.UPSTREAM_API_URL;
+    else process.env.UPSTREAM_API_URL = previousUrl;
+  }
+});
+
+test("rejects an upstream host outside the manifest allowlist", async () => {
+  const previousUrl = process.env.UPSTREAM_API_URL;
+  process.env.UPSTREAM_API_URL = "https://attacker.example";
+  try {
+    await assert.rejects(
+      connector.invoke({
+        protocol_version: 1,
+        request_id: "template-request-2",
+        connector: { id: connector.manifest.id, version: connector.manifest.version },
+        tool: "get_pools",
+        arguments: { chain: "base" },
+        context: {},
+      }),
+      /permissions\.network_hosts/
+    );
+  } finally {
+    if (previousUrl === undefined) delete process.env.UPSTREAM_API_URL;
+    else process.env.UPSTREAM_API_URL = previousUrl;
+  }
+});

package/connectors/templates/read-only/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}

package/hermes/plugins/agent_wallet/plugin.yaml

@@ -1,5 +1,5 @@
 name: agent-wallet
-version: 0.1.101
+version: 0.1.103
 description: Thin Hermes Agent bridge to the existing AgentLayer/OpenClaw wallet backend
 provides_tools:
   - agent_wallet_tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentlayer.tech/wallet",
-  "version": "0.1.101",
+  "version": "0.1.103",
   "description": "Universal AgentLayer wallet installer for OpenClaw, Codex, Claude Code, and Hermes.",
   "type": "module",
   "repository": {
@@ -52,6 +52,7 @@
     ".openclaw/extensions/agent-wallet/",
     ".claude-plugin/marketplace.json",
     "codex/plugins/agent-wallet/",
+    "connectors/",
     "claude-code/plugins/agent-wallet/",
     "hermes/plugins/agent_wallet/",
     "wdk-btc-wallet/src/",

package/wdk-btc-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-btc-wallet",
-  "version": "0.1.101",
+  "version": "0.1.103",
   "private": true,
   "type": "module",
   "description": "Separate BTC-only wallet service built on Tether WDK.",

package/wdk-evm-wallet/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wdk-evm-wallet",
-  "version": "0.1.101",
+  "version": "0.1.103",
   "private": true,
   "type": "module",
   "description": "Separate EVM wallet service built on Tether WDK.",