kompass-sdk 0.14.0 → 0.16.0

package/src/sources/locus.ts

@@ -0,0 +1,156 @@
+/**
+ * Locus Wrapped API Source Adapter
+ * Fetches Locus's live API catalog and indexes 50+ pay-per-use providers
+ * as discoverable capabilities. Each wrapped API becomes a searchable agent.
+ * Agents pay per-call via USDC on Base — no upstream API keys needed.
+ *
+ * Docs: https://beta.paywithlocus.com/skill.md
+ * Live index: https://beta.paywithlocus.com/wapi/index.md
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+const LOCUS_API = "https://beta-api.paywithlocus.com/api";
+const WAPI_INDEX_URL = "https://beta.paywithlocus.com/wapi/index.md";
+
+interface LocusProvider {
+  name: string;
+  slug: string;
+  category: string;
+  endpoints: string;
+  description: string;
+}
+
+// Cache fetched providers — refresh every 10 minutes
+let providerCache: LocusProvider[] | null = null;
+let cacheTime = 0;
+const CACHE_TTL = 10 * 60 * 1000;
+
+/**
+ * Parse the live markdown index from Locus into structured provider data.
+ * The index is a markdown table with columns: Provider, Category, Endpoints, Description
+ */
+function parseMarkdownIndex(md: string): LocusProvider[] {
+  const providers: LocusProvider[] = [];
+  const lines = md.split("\n");
+
+  for (const line of lines) {
+    // Match table rows: | [Provider Name](url) | Category | Endpoints | Description |
+    const match = line.match(/^\| \[([^\]]+)\]\(https:\/\/[^)]*\/wapi\/([^.]+)\.md\)\s*\|\s*([^|]+)\|\s*([^|]+)\|\s*([^|]+)\|/);
+    if (match) {
+      providers.push({
+        name: match[1].trim(),
+        slug: match[2].trim(),
+        category: match[3].trim().toLowerCase(),
+        endpoints: match[4].trim(),
+        description: match[5].trim(),
+      });
+    }
+  }
+
+  return providers;
+}
+
+async function fetchProviders(timeout: number): Promise<LocusProvider[]> {
+  if (providerCache && Date.now() - cacheTime < CACHE_TTL) {
+    return providerCache;
+  }
+
+  try {
+    const res = await fetch(WAPI_INDEX_URL, {
+      signal: AbortSignal.timeout(timeout),
+    });
+
+    if (!res.ok) return providerCache ?? [];
+
+    const md = await res.text();
+    const parsed = parseMarkdownIndex(md);
+
+    if (parsed.length > 0) {
+      providerCache = parsed;
+      cacheTime = Date.now();
+    }
+
+    return providerCache ?? [];
+  } catch {
+    return providerCache ?? [];
+  }
+}
+
+export const locusAdapter: SourceAdapter = {
+  name: "locus" as any,
+  displayName: "Locus Wrapped APIs",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    const limit = options?.limit ?? 20;
+    const timeout = options?.timeout ?? 10000;
+    const lower = query.toLowerCase();
+    const terms = lower.split(/\s+/).filter(t => t.length > 2);
+
+    const providers = await fetchProviders(timeout);
+
+    // Score each provider by relevance
+    const scored = providers.map(provider => {
+      let score = 0;
+      const searchText = `${provider.name} ${provider.description} ${provider.category} ${provider.endpoints}`.toLowerCase();
+
+      for (const term of terms) {
+        if (provider.name.toLowerCase().includes(term)) score += 5;
+        if (provider.description.toLowerCase().includes(term)) score += 3;
+        if (provider.endpoints.toLowerCase().includes(term)) score += 2;
+        if (provider.category.includes(term)) score += 4;
+        if (searchText.includes(term)) score += 1;
+      }
+
+      return { provider, score };
+    })
+      .filter(s => s.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+
+    return scored.map(s => mapLocusProvider(s.provider));
+  },
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await fetch(WAPI_INDEX_URL, {
+        signal: AbortSignal.timeout(5000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+};
+
+function mapLocusProvider(provider: LocusProvider): UnifiedAgent {
+  const endpointList = provider.endpoints.split(",").map(e => e.trim()).slice(0, 5);
+
+  return {
+    id: `locus:${provider.slug}`,
+    nativeId: provider.slug,
+    name: `${provider.name} (via Locus)`,
+    description: `${provider.description} Pay-per-use via USDC — no API key needed.`,
+    categories: [provider.category.split(" / ")[0].toLowerCase(), "api", "pay-per-use"],
+    capabilities: endpointList.map(e => `${provider.name}: ${e}`),
+    source: "locus" as any,
+    protocol: "http",
+    endpoints: {
+      http: `${LOCUS_API}/wrapped/${provider.slug}`,
+    },
+    pricing: {
+      model: "per-call",
+      amount: "0.01",
+      currency: "USDC",
+    },
+    verified: true,
+    lastSeen: Date.now(),
+    raw: {
+      type: "locus-wrapped-api",
+      provider: provider.slug,
+      category: provider.category,
+      endpoints: endpointList,
+      allEndpoints: provider.endpoints,
+    },
+  };
+}

package/src/sources/olas.ts

@@ -0,0 +1,171 @@
+/**
+ * Olas Mech Marketplace Source Adapter
+ * Queries the Olas marketplace subgraph (The Graph) to discover AI agent mechs.
+ * Mechs are autonomous agents that accept prompts and return deliverables.
+ * Supports Gnosis, Base, Polygon, Optimism chains.
+ *
+ * Subgraph: https://api.subgraph.autonolas.tech/api/proxy/marketplace-{chain}
+ * Docs: https://docs.olas.network
+ */
+
+import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
+
+const SUBGRAPH_URLS: Record<string, string> = {
+  gnosis: "https://api.subgraph.autonolas.tech/api/proxy/marketplace-gnosis",
+  base: "https://api.subgraph.autonolas.tech/api/proxy/marketplace-base",
+};
+
+const MECH_AGENTS_QUERY = `{
+  mechAgents(first: 50, orderBy: totalTransactions, orderDirection: desc) {
+    id
+    address
+    agentHash
+    totalTransactions
+    service {
+      serviceId
+      totalRequests
+      totalDeliveries
+    }
+  }
+}`;
+
+interface MechAgent {
+  id: string;
+  address: string;
+  agentHash: string;
+  totalTransactions: string;
+  service?: {
+    serviceId: string;
+    totalRequests: string;
+    totalDeliveries: string;
+  };
+}
+
+// Cache mechs — refresh every 10 minutes
+let mechCache: MechAgent[] | null = null;
+let cacheTime = 0;
+const CACHE_TTL = 10 * 60 * 1000;
+
+async function fetchMechs(timeout: number): Promise<MechAgent[]> {
+  if (mechCache && Date.now() - cacheTime < CACHE_TTL) {
+    return mechCache;
+  }
+
+  const allMechs: MechAgent[] = [];
+
+  // Query both Gnosis and Base subgraphs
+  for (const [chain, url] of Object.entries(SUBGRAPH_URLS)) {
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ query: MECH_AGENTS_QUERY }),
+        signal: AbortSignal.timeout(timeout),
+      });
+
+      if (!res.ok) continue;
+
+      const json = await res.json();
+      const agents = json.data?.mechAgents ?? [];
+
+      for (const agent of agents) {
+        allMechs.push({ ...agent, _chain: chain } as any);
+      }
+    } catch {
+      // Chain subgraph unavailable, continue with others
+    }
+  }
+
+  if (allMechs.length > 0) {
+    mechCache = allMechs;
+    cacheTime = Date.now();
+  }
+
+  return mechCache ?? [];
+}
+
+export const olasAdapter: SourceAdapter = {
+  name: "olas" as any,
+  displayName: "Olas Mech Marketplace",
+
+  async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
+    const limit = options?.limit ?? 20;
+    const timeout = options?.timeout ?? 10000;
+
+    try {
+      const mechs = await fetchMechs(timeout);
+
+      if (!query) return mechs.slice(0, limit).map(mapMech);
+
+      // Score mechs by transaction volume and filter by relevance
+      // Since mechs don't have descriptions, match against known tool categories
+      const lower = query.toLowerCase();
+      const relevant = mechs.filter(() => {
+        // Olas mechs handle: predictions, research, analysis, trading signals
+        const olasKeywords = ["predict", "research", "analyze", "trade", "ai", "agent", "mech", "autonomous", "forecast", "oracle", "data"];
+        return olasKeywords.some(k => lower.includes(k)) || true; // Return all if query is general
+      });
+
+      return relevant
+        .sort((a, b) => parseInt(b.totalTransactions) - parseInt(a.totalTransactions))
+        .slice(0, limit)
+        .map(mapMech);
+    } catch {
+      return [];
+    }
+  },
+
+  async ping(): Promise<boolean> {
+    try {
+      const res = await fetch(SUBGRAPH_URLS.gnosis, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ query: "{ global(id: \"global\") { totalMechs } }" }),
+        signal: AbortSignal.timeout(5000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
+  },
+};
+
+function mapMech(mech: MechAgent): UnifiedAgent {
+  const chain = (mech as any)._chain || "gnosis";
+  const txCount = parseInt(mech.totalTransactions) || 0;
+  const deliveries = parseInt(mech.service?.totalDeliveries || "0");
+  const requests = parseInt(mech.service?.totalRequests || "0");
+  const successRate = requests > 0 ? Math.round((deliveries / requests) * 100) : 0;
+
+  return {
+    id: `olas:${chain}:${mech.address}`,
+    nativeId: mech.address,
+    name: `Olas Mech ${mech.address.slice(0, 8)}...${mech.address.slice(-4)}`,
+    description: `Autonomous AI agent on Olas Marketplace (${chain}). ${txCount} transactions, ${deliveries} deliveries. Accepts prompts and returns AI-powered results via on-chain requests.`,
+    categories: ["ai", "autonomous", "prediction"],
+    capabilities: [
+      "AI prompt execution",
+      "Prediction markets",
+      "Research and analysis",
+      "On-chain autonomous operation",
+    ],
+    source: "olas" as any,
+    protocol: "http",
+    endpoints: {
+      http: `https://mech.tech/mech/${mech.address}`,
+    },
+    reputation: {
+      score: successRate,
+      count: deliveries,
+      source: `olas-${chain}`,
+    },
+    pricing: {
+      model: "per-call",
+      amount: "0.01",
+      currency: "OLAS",
+    },
+    verified: txCount > 10,
+    lastSeen: txCount > 0 ? Date.now() : undefined,
+    raw: mech,
+  };
+}

package/src/sources/types.ts

@@ -14,7 +14,10 @@ export type AgentSource =
   | "adp"
   | "a2a-wellknown"
   | "l402-directory"
-  | "skills-registry";
+  | "skills-registry"
+  | "bankr"
+  | "locus"
+  | "olas";
 
 export type AgentProtocol = "acp" | "mcp" | "x402" | "a2a" | "http" | "l402" | "onchain" | "skill";
 

package/src/wallet/bridge.ts

@@ -19,6 +19,10 @@ const USDC_ADDRESSES: Record<string, Address> = {
   "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
 };
 
+// Kompass treasury address — receives platform fee on payments
+const KOMPASS_TREASURY: Address = "0x2aB73f8CCee4ABE601cE71eCC82Bd9eC375FeBbA";
+const PLATFORM_FEE_BPS = 200; // 2% = 200 basis points
+
 // ── ACP Wallet Topup ─────────────────────────────────────
 
 /**
@@ -29,12 +33,17 @@ export async function topupACPWallet(
   wallet: KompassWallet,
   acpWalletAddress: Address,
   amountUSDC: number
-): Promise<{ txHash: Hex; amount: string }> {
+): Promise<{ txHash: Hex; amount: string; fee?: string }> {
   const network = wallet.getNetwork();
   const usdcAddress = USDC_ADDRESSES[network];
   if (!usdcAddress) throw new Error(`No USDC address for network: ${network}`);
 
-  const amount = parseUnits(String(amountUSDC), 6);
+  // Calculate platform fee (2%)
+  const feeUSDC = amountUSDC * PLATFORM_FEE_BPS / 10000;
+  const netAmount = amountUSDC - feeUSDC;
+  const totalNeeded = parseUnits(String(amountUSDC), 6);
+  const netAmountRaw = parseUnits(String(netAmount.toFixed(6)), 6);
+  const feeAmountRaw = totalNeeded - netAmountRaw;
 
   // Check balance first
   const balance = await wallet.getPublicClient().readContract({
@@ -44,25 +53,43 @@ export async function topupACPWallet(
     args: [wallet.getAddress()],
   });
 
-  if (balance < amount) {
+  if (balance < totalNeeded) {
     throw new Error(
       `Insufficient USDC: have ${formatUnits(balance, 6)}, need ${amountUSDC}. ` +
       `Fund your Kompass wallet at ${wallet.getAddress()} on ${network}.`
     );
   }
 
+  // Transfer net amount to ACP wallet
   const txHash = await (wallet.getWalletClient() as any).writeContract({
     address: usdcAddress,
     abi: USDC_ABI,
     functionName: "transfer",
-    args: [acpWalletAddress, amount],
+    args: [acpWalletAddress, netAmountRaw],
   });
 
   await wallet.getPublicClient().waitForTransactionReceipt({ hash: txHash });
 
-  console.log(`[Kompass Bridge] Transferred ${amountUSDC} USDC to ACP wallet ${acpWalletAddress.slice(0, 10)}... | tx: ${txHash}`);
+  // Transfer platform fee to Kompass treasury (skip if treasury == ACP wallet)
+  if (feeAmountRaw > 0n && KOMPASS_TREASURY.toLowerCase() !== acpWalletAddress.toLowerCase()) {
+    try {
+      const feeTx = await (wallet.getWalletClient() as any).writeContract({
+        address: usdcAddress,
+        abi: USDC_ABI,
+        functionName: "transfer",
+        args: [KOMPASS_TREASURY, feeAmountRaw],
+      });
+      await wallet.getPublicClient().waitForTransactionReceipt({ hash: feeTx });
+      console.log(`[Kompass Bridge] Platform fee: $${feeUSDC.toFixed(4)} USDC → treasury | tx: ${feeTx}`);
+    } catch (feeErr) {
+      // Fee transfer failure shouldn't block the job
+      console.log(`[Kompass Bridge] Fee transfer failed (non-blocking): ${feeErr instanceof Error ? feeErr.message : feeErr}`);
+    }
+  }
+
+  console.log(`[Kompass Bridge] Transferred ${netAmount.toFixed(4)} USDC to ACP wallet ${acpWalletAddress.slice(0, 10)}... | tx: ${txHash}`);
 
-  return { txHash, amount: String(amountUSDC) };
+  return { txHash, amount: String(netAmount.toFixed(4)), fee: feeUSDC.toFixed(4) };
 }
 
 // ── Lightning Swap (USDC → sats) ─────────────────────────

package/src/wallet/handlers/acp.ts

@@ -40,9 +40,10 @@ export async function handleACPPayment(
     // Job creation (REQUEST) and acceptance (NEGOTIATION) are FREE.
     // We topup only after confirming an agent accepted.
 
-    // Use ACP CLI with execFile (not execSync) to avoid shell injection
-    // Arguments passed as array, not concatenated string
-    const requirements = JSON.stringify({ description: task });
+    // Format requirements to match offering's expected schema.
+    // If the offering has a requirement template/schema, try to conform to it.
+    // Otherwise fall back to {description: task}.
+    const requirements = JSON.stringify(formatRequirements(task, offering));
 
     const { stdout } = await execFileAsync(
       "npx",
@@ -157,3 +158,68 @@ export async function handleACPPayment(
     };
   }
 }
+
+/**
+ * Format task requirements to match the offering's expected schema.
+ *
+ * ACP agents reject jobs when requirements don't match their offering's
+ * expected input format. This function:
+ * 1. Checks if the offering has a requirement schema/template
+ * 2. Tries to extract relevant fields from the natural language task
+ * 3. Falls back to {description: task} if no schema exists
+ */
+function formatRequirements(task: string, offering: any): Record<string, unknown> {
+  const schema = offering.requirement ?? offering.requirementSchema ?? offering.inputSchema;
+
+  // No schema defined — send description (most flexible)
+  if (!schema || typeof schema === "string") {
+    return { description: task };
+  }
+
+  // Schema is an object — try to populate its fields from the task
+  if (typeof schema === "object") {
+    const formatted: Record<string, unknown> = {};
+    const taskLower = task.toLowerCase();
+
+    for (const [key, spec] of Object.entries(schema)) {
+      const keyLower = key.toLowerCase();
+
+      // Try to extract Ethereum addresses for address-type fields
+      if (keyLower.includes("address") || keyLower.includes("token") || keyLower.includes("contract")) {
+        const addrMatch = task.match(/0x[a-fA-F0-9]{40}/);
+        if (addrMatch) {
+          formatted[key] = addrMatch[0];
+          continue;
+        }
+      }
+
+      // Try to extract chain/network
+      if (keyLower.includes("chain") || keyLower.includes("network")) {
+        const chains = ["base", "ethereum", "polygon", "arbitrum", "optimism", "bsc"];
+        const found = chains.find((c) => taskLower.includes(c));
+        formatted[key] = found ?? "base";
+        continue;
+      }
+
+      // Try to extract numeric amounts
+      if (keyLower.includes("amount") || keyLower.includes("quantity") || keyLower.includes("limit")) {
+        const numMatch = task.match(/\d+\.?\d*/);
+        if (numMatch) {
+          formatted[key] = parseFloat(numMatch[0]);
+          continue;
+        }
+      }
+
+      // For any other field, use the task description as the value
+      if (typeof spec === "string") {
+        formatted[key] = task; // Use full task as the value
+      }
+    }
+
+    // Always include description for context
+    formatted.description = task;
+    return formatted;
+  }
+
+  return { description: task };
+}

package/src/wallet/handlers/bankr.ts

@@ -0,0 +1,108 @@
+/**
+ * Bankr Payment Handler
+ * Routes trading tasks through Bankr's LLM Gateway
+ * POST prompt → poll for result
+ */
+
+import type { KompassWallet } from "../index.js";
+import type { UnifiedAgent } from "../../sources/types.js";
+
+const BANKR_API = "https://api.bankr.bot";
+
+export async function handleBankrPayment(
+  wallet: KompassWallet,
+  agent: UnifiedAgent,
+  task: string,
+): Promise<{ success: boolean; deliverable?: unknown; jobId?: string }> {
+  const apiKey = process.env.BANKR_API_KEY;
+  if (!apiKey) {
+    return {
+      success: false,
+      deliverable: {
+        error: "BANKR_API_KEY not configured. Set the BANKR_API_KEY environment variable.",
+        hint: "Get an API key from https://bankr.bot",
+      },
+    };
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-API-Key": apiKey,
+  };
+
+  try {
+    // Step 1: Submit prompt
+    const submitRes = await fetch(`${BANKR_API}/agent/prompt`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({ prompt: task }),
+      signal: AbortSignal.timeout(30000),
+    });
+
+    if (!submitRes.ok) {
+      const errBody = await submitRes.text().catch(() => "");
+      return {
+        success: false,
+        deliverable: { error: `Bankr API error: ${submitRes.status}`, details: errBody },
+      };
+    }
+
+    const submitData = await submitRes.json();
+    const jobId = submitData.jobId ?? submitData.job_id ?? submitData.id;
+
+    // If the response is immediate (no job polling needed)
+    if (!jobId || submitData.result || submitData.response) {
+      return {
+        success: true,
+        deliverable: submitData.result ?? submitData.response ?? submitData,
+      };
+    }
+
+    // Step 2: Poll for result
+    const maxAttempts = 30;
+    const pollInterval = 2000;
+
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+
+      const pollRes = await fetch(`${BANKR_API}/agent/job/${jobId}`, {
+        headers,
+        signal: AbortSignal.timeout(10000),
+      });
+
+      if (!pollRes.ok) continue;
+
+      const pollData = await pollRes.json();
+      const status = pollData.status?.toLowerCase();
+
+      if (status === "completed" || status === "done" || status === "success") {
+        return {
+          success: true,
+          deliverable: pollData.result ?? pollData.response ?? pollData,
+          jobId,
+        };
+      }
+
+      if (status === "failed" || status === "error") {
+        return {
+          success: false,
+          deliverable: { error: pollData.error ?? "Job failed", details: pollData },
+          jobId,
+        };
+      }
+
+      // Still pending, continue polling
+    }
+
+    return {
+      success: false,
+      deliverable: { error: "Job timed out after polling", jobId },
+      jobId,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      deliverable: { error: err instanceof Error ? err.message : String(err) },
+    };
+  }
+}