kompass-sdk 0.3.0 → 0.5.0

package/src/sources/x402-ecosystem.ts

@@ -1,86 +1,103 @@
 /**
- * x402 Ecosystem Source Adapter
- * Fetches known x402 endpoints from the x402.org ecosystem
+ * x402/L402/MPP Ecosystem Source Adapter
+ * Searches 402index.io — protocol-agnostic directory of 15,000+ paid API endpoints
+ * Covers x402, L402, and MPP endpoints
  */
 
 import type { SourceAdapter, UnifiedAgent, SourceSearchOptions } from "./types.js";
 
-// Seed list of known x402 services (from x402.org/ecosystem + x402scan)
-const KNOWN_X402_SERVICES = [
-  { name: "OpenRouter", url: "https://openrouter.ai", description: "LLM API access with USDC payments", categories: ["ai", "llm"] },
-  { name: "Dexter AI", url: "https://dexterai.com", description: "x402 facilitator on Solana. 38M+ settlements", categories: ["defi", "trading"] },
-  { name: "AgentCash", url: "https://agentcash.dev", description: "One balance, every paid API. Multi-protocol agent wallet", categories: ["payments", "tools"] },
-  { name: "Allium", url: "https://allium.so", description: "Blockchain data APIs with x402 payments", categories: ["data", "analytics"] },
-  { name: "Kompass Data Provider", url: "http://localhost:4021", description: "DeFi yield data, token prices, risk scores via x402", categories: ["defi", "data"] },
-  { name: "Wurk", url: "https://wurk.fun", description: "Agent job board with x402 integration", categories: ["jobs", "tools"] },
-  { name: "Tavily", url: "https://tavily.com", description: "AI-powered web search API", categories: ["search", "data"] },
-  { name: "ASSAY", url: "https://assayaudit.com", description: "Agent evaluation and auditing service", categories: ["audit", "trust"] },
-  { name: "Zentiece", url: "https://zentiece.com", description: "Agent with x402 payments + ORBIT burns", categories: ["defi", "trading"] },
-  { name: "AlgoVoi", url: "https://algovoi.com", description: "x402 integration on Algorand", categories: ["defi", "tools"] },
-  { name: "LibertAI", url: "https://libertai.io", description: "Autonomous agents on Aleph Cloud with x402", categories: ["ai", "compute"] },
-  { name: "Handshake_58", url: "https://handshake58.com", description: "Streaming AI agent payment channels", categories: ["payments"] },
-];
+const INDEX_API = "https://402index.io/api/v1/services";
 
 export const x402EcosystemAdapter: SourceAdapter = {
   name: "x402-ecosystem",
-  displayName: "x402 Ecosystem",
+  displayName: "402 Index (x402 + L402 + MPP)",
 
   async search(query: string, options?: SourceSearchOptions): Promise<UnifiedAgent[]> {
-    // Also try to fetch from x402.org ecosystem page
-    let dynamicServices: typeof KNOWN_X402_SERVICES = [];
+    const limit = options?.limit ?? 20;
+    const timeout = options?.timeout ?? 10000;
+
     try {
-      const res = await fetch("https://www.x402.org/ecosystem", {
-        signal: AbortSignal.timeout(options?.timeout ?? 5000),
+      const url = new URL(INDEX_API);
+      if (query) url.searchParams.set("q", query);
+      url.searchParams.set("limit", String(limit));
+      url.searchParams.set("health", "healthy");
+      url.searchParams.set("sort", "reliability");
+
+      const res = await fetch(url.toString(), {
+        signal: AbortSignal.timeout(timeout),
       });
-      if (res.ok) {
-        const html = await res.text();
-        // Extract any JSON data from the page
-        const jsonMatch = html.match(/\[{.*"name".*}\]/s);
-        if (jsonMatch) {
-          dynamicServices = JSON.parse(jsonMatch[0]);
-        }
-      }
+
+      if (!res.ok) return [];
+
+      const data = await res.json();
+      const services = data.services ?? data.data ?? data;
+
+      if (!Array.isArray(services)) return [];
+
+      return services.slice(0, limit).map(mapService);
     } catch {
-      // Fall back to seed list
+      return [];
     }
-
-    const allServices = [...KNOWN_X402_SERVICES, ...dynamicServices];
-    const lower = query.toLowerCase();
-
-    return allServices
-      .filter((s) => {
-        if (!query) return true;
-        return (
-          s.name.toLowerCase().includes(lower) ||
-          s.description.toLowerCase().includes(lower) ||
-          s.categories.some((c) => lower.includes(c))
-        );
-      })
-      .slice(0, options?.limit ?? 50)
-      .map(mapX402Service);
   },
 
   async ping(): Promise<boolean> {
-    return true; // Seed list always available
+    try {
+      const res = await fetch(`${INDEX_API}?limit=1`, {
+        signal: AbortSignal.timeout(5000),
+      });
+      return res.ok;
+    } catch {
+      return false;
+    }
   },
 };
 
-function mapX402Service(service: (typeof KNOWN_X402_SERVICES)[0]): UnifiedAgent {
+function mapService(service: any): UnifiedAgent {
+  const protocol = mapProtocol(service.protocol);
+
   return {
-    id: `x402-ecosystem:${service.name.toLowerCase().replace(/\s+/g, "-")}`,
-    nativeId: service.name,
-    name: service.name,
-    description: service.description,
-    categories: service.categories,
-    capabilities: [service.description],
+    id: `x402-ecosystem:${service.id ?? service.url}`,
+    nativeId: service.id ?? service.name,
+    name: cleanName(service.name ?? "Unknown Service"),
+    description: cleanDescription(service.description ?? ""),
+    categories: service.category ? service.category.split("/").map((c: string) => c.trim()) : ["general"],
+    capabilities: [service.description ?? service.name ?? ""].filter(Boolean),
     source: "x402-ecosystem",
-    protocol: "x402",
+    protocol,
     endpoints: {
-      x402: service.url,
+      x402: protocol === "x402" ? service.url : undefined,
+      l402: protocol === "l402" ? service.url : undefined,
       http: service.url,
     },
-    pricing: { model: "per-call", currency: "USDC" },
-    verified: true,
+    pricing: {
+      model: "per-call",
+      amount: service.price_usd ? String(service.price_usd) : service.price_sats ? `${service.price_sats} sats` : undefined,
+      currency: service.payment_asset ?? (protocol === "l402" ? "sats" : "USDC"),
+    },
+    reputation: service.reliability_score ? {
+      score: service.reliability_score,
+      count: service.uptime_30d ? Math.round(service.uptime_30d * 100) : 0,
+      source: "402index",
+    } : undefined,
+    verified: service.x402_payment_valid === 1 || service.health_status === "healthy",
+    lastSeen: service.last_checked ? new Date(service.last_checked).getTime() : undefined,
     raw: service,
   };
 }
+
+function mapProtocol(protocol: string): "x402" | "l402" | "http" {
+  switch (protocol?.toLowerCase()) {
+    case "x402": return "x402";
+    case "l402": return "l402";
+    case "mpp": return "x402"; // MPP uses same HTTP 402 pattern
+    default: return "x402";
+  }
+}
+
+function cleanName(name: string): string {
+  return name.replace(/^\s+|\s+$/g, "").split("\n")[0].trim().slice(0, 100);
+}
+
+function cleanDescription(desc: string): string {
+  return desc.replace(/^\s+|\s+$/g, "").replace(/\s+/g, " ").slice(0, 300);
+}

package/src/unified.ts

@@ -28,6 +28,8 @@ export interface UnifiedConfig {
   kompassConfig?: any;
   /** ERC-8004 reputation writer config (writes feedback after executions) */
   reputationWriter?: ReputationWriterConfig;
+  /** Kompass wallet for payments */
+  wallet?: any;
 }
 
 export interface FindOptions {
@@ -59,7 +61,7 @@ export class KompassUnified {
     this.config = config;
     this.aggregator = new Aggregator(adapters);
     this.bridge = bridge;
-    this.router = new CapabilityRouter(this.aggregator, this.bridge, config?.reputationWriter);
+    this.router = new CapabilityRouter(this.aggregator, this.bridge, config?.reputationWriter, config?.wallet);
   }
 
   static async create(config?: UnifiedConfig): Promise<KompassUnified> {

package/src/wallet/bridge.ts

@@ -0,0 +1,164 @@
+/**
+ * Kompass Internal Bridge
+ * Handles all fund routing that the agent never sees:
+ * - USDC transfer to ACP wallet (same chain)
+ * - USDC → Lightning sats swap (via Boltz)
+ * - Cross-chain USDC bridging (via CCTP)
+ */
+
+import { type Address, type Hex, parseUnits, formatUnits } from "viem";
+import type { KompassWallet } from "./index.js";
+
+const USDC_ABI = [
+  { type: "function", name: "transfer", inputs: [{ name: "to", type: "address" }, { name: "amount", type: "uint256" }], outputs: [{ name: "", type: "bool" }], stateMutability: "nonpayable" },
+  { type: "function", name: "balanceOf", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }], stateMutability: "view" },
+] as const;
+
+const USDC_ADDRESSES: Record<string, Address> = {
+  "base": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+  "base-sepolia": "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+};
+
+// ── ACP Wallet Topup ─────────────────────────────────────
+
+/**
+ * Transfer USDC from Kompass wallet to ACP smart wallet on Base.
+ * This is a simple ERC-20 transfer on the same chain.
+ */
+export async function topupACPWallet(
+  wallet: KompassWallet,
+  acpWalletAddress: Address,
+  amountUSDC: number
+): Promise<{ txHash: Hex; amount: 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);
+
+  // Check balance first
+  const balance = await wallet.getPublicClient().readContract({
+    address: usdcAddress,
+    abi: USDC_ABI,
+    functionName: "balanceOf",
+    args: [wallet.getAddress()],
+  });
+
+  if (balance < amount) {
+    throw new Error(
+      `Insufficient USDC: have ${formatUnits(balance, 6)}, need ${amountUSDC}. ` +
+      `Fund your Kompass wallet at ${wallet.getAddress()} on ${network}.`
+    );
+  }
+
+  const txHash = await (wallet.getWalletClient() as any).writeContract({
+    address: usdcAddress,
+    abi: USDC_ABI,
+    functionName: "transfer",
+    args: [acpWalletAddress, amount],
+  });
+
+  await wallet.getPublicClient().waitForTransactionReceipt({ hash: txHash });
+
+  console.log(`[Kompass Bridge] Transferred ${amountUSDC} USDC to ACP wallet ${acpWalletAddress.slice(0, 10)}... | tx: ${txHash}`);
+
+  return { txHash, amount: String(amountUSDC) };
+}
+
+// ── Lightning Swap (USDC → sats) ─────────────────────────
+
+/**
+ * Swap USDC to Lightning sats via Boltz Exchange API.
+ * Boltz supports atomic submarine swaps: USDC on-chain → Lightning invoice paid.
+ */
+export async function swapUSDCtoLightning(
+  wallet: KompassWallet,
+  invoiceAmountSats: number,
+  invoice: string
+): Promise<{ success: boolean; preimage?: string; error?: string }> {
+  // Boltz Exchange API for submarine swaps
+  // https://docs.boltz.exchange/api
+  const BOLTZ_API = "https://api.boltz.exchange/v2";
+
+  try {
+    // Step 1: Create a submarine swap (on-chain → Lightning)
+    const createRes = await fetch(`${BOLTZ_API}/swap/submarine`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        from: "USDC", // or "BTC" for on-chain BTC
+        to: "BTC",
+        invoice,
+        referralId: "kompass",
+      }),
+    });
+
+    if (!createRes.ok) {
+      const err = await createRes.text();
+      return { success: false, error: `Boltz swap creation failed: ${err}` };
+    }
+
+    const swapData = await createRes.json();
+
+    // Step 2: Send the required on-chain amount to Boltz's lock address
+    // Boltz provides: address, expectedAmount, and a swap ID
+    // The agent's wallet sends USDC/BTC to the lock address
+    // Boltz atomically pays the Lightning invoice
+
+    return {
+      success: false,
+      error: `Lightning swap prepared via Boltz. Swap ID: ${swapData.id ?? "unknown"}. ` +
+        `Send ${swapData.expectedAmount ?? invoiceAmountSats} sats worth of USDC to ${swapData.address ?? "Boltz lock address"} to complete.`,
+    };
+  } catch (err) {
+    return {
+      success: false,
+      error: `Lightning swap failed: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+}
+
+// ── Cross-Chain USDC Bridge ──────────────────────────────
+
+/**
+ * Bridge USDC from Base to another chain via Circle CCTP.
+ * Most agent capabilities are on Base, so this is rarely needed.
+ */
+export async function bridgeUSDCCrossChain(
+  wallet: KompassWallet,
+  toChain: string,
+  amountUSDC: number
+): Promise<{ success: boolean; txHash?: string; error?: string }> {
+  // Circle CCTP (Cross-Chain Transfer Protocol) endpoints
+  // https://developers.circle.com/stablecoins/cctp-getting-started
+
+  // For hackathon: most capabilities are on Base, bridging rarely needed
+  return {
+    success: false,
+    error: `Cross-chain bridging to ${toChain} is not yet automated. ` +
+      `Most agent capabilities are on Base. Use a bridge like bridge.circle.com manually if needed.`,
+  };
+}
+
+// ── Balance Check ────────────────────────────────────────
+
+/**
+ * Check if wallet has enough USDC for a payment.
+ * Returns true if sufficient, throws descriptive error if not.
+ */
+export async function ensureSufficientBalance(
+  wallet: KompassWallet,
+  requiredUSDC: number
+): Promise<boolean> {
+  const balance = await wallet.getBalance();
+  const available = parseFloat(balance.usdc);
+
+  if (available < requiredUSDC) {
+    throw new Error(
+      `Insufficient USDC: have $${available.toFixed(2)}, need $${requiredUSDC.toFixed(2)}. ` +
+      `Fund your Kompass wallet: send USDC to ${balance.address} on Base.`
+    );
+  }
+
+  return true;
+}

package/src/wallet/handlers/acp.ts

@@ -10,9 +10,14 @@ import { execFile } from "child_process";
 import { promisify } from "util";
 import type { KompassWallet } from "../index.js";
 import type { UnifiedAgent } from "../../sources/types.js";
+import { topupACPWallet } from "../bridge.js";
+import type { Address } from "viem";
 
 const execFileAsync = promisify(execFile);
 
+// ACP wallet address (from our registration)
+const ACP_WALLET = "0x2aB73f8CCee4ABE601cE71eCC82Bd9eC375FeBbA" as Address;
+
 export async function handleACPPayment(
   wallet: KompassWallet,
   agent: UnifiedAgent,
@@ -30,6 +35,16 @@ export async function handleACPPayment(
   }
 
   try {
+    // Auto-topup: transfer USDC from Kompass wallet to ACP wallet if needed
+    const jobPrice = offering.price ?? 0.05;
+    const topupAmount = Math.max(jobPrice * 2, 0.10); // 2x buffer
+    try {
+      await topupACPWallet(wallet, ACP_WALLET, topupAmount);
+    } catch (topupErr) {
+      // Topup may fail if wallet is on different network or insufficient funds
+      console.log(`[Kompass] ACP topup skipped: ${topupErr instanceof Error ? topupErr.message : topupErr}`);
+    }
+
     // Use ACP CLI with execFile (not execSync) to avoid shell injection
     // Arguments passed as array, not concatenated string
     const requirements = JSON.stringify({ description: task });
@@ -39,7 +54,7 @@ export async function handleACPPayment(
       [
         "acp", "job", "create",
         walletAddress,
-        String(offering.id),
+        String(offering.name ?? offering.id),
         "--requirements", requirements,
         "--isAutomated", "true",
         "--json",
@@ -52,19 +67,64 @@ export async function handleACPPayment(
     );
 
     const jobData = JSON.parse(stdout.trim());
+    const jobId = jobData.data?.jobId ?? jobData.jobId ?? jobData.id;
+
+    console.log(`[Kompass] ACP job #${jobId} created with ${agent.name}. Polling for completion...`);
+
+    // Poll for completion (max 2 minutes)
+    const maxWait = 120_000;
+    const pollInterval = 10_000;
+    const start = Date.now();
+    let finalPhase = "created";
+    let deliverable: any = null;
+
+    while (Date.now() - start < maxWait) {
+      await new Promise((r) => setTimeout(r, pollInterval));
+
+      try {
+        const { stdout: statusOut } = await execFileAsync(
+          "npx",
+          ["acp", "job", "status", String(jobId), "--json"],
+          { cwd: "/tmp/openclaw-acp", timeout: 15000, env: { ...process.env, NODE_NO_WARNINGS: "1" } }
+        );
+
+        const statusData = JSON.parse(statusOut.trim());
+        finalPhase = statusData.phase ?? "unknown";
+        console.log(`[Kompass] Job #${jobId} phase: ${finalPhase}`);
+
+        if (finalPhase === "COMPLETED") {
+          deliverable = statusData.deliverable;
+          break;
+        }
+        if (finalPhase === "REJECTED" || finalPhase === "EXPIRED" || finalPhase === "CANCELLED") {
+          break;
+        }
+      } catch {
+        // Status check failed, keep polling
+      }
+    }
+
+    if (finalPhase === "COMPLETED" && deliverable) {
+      return {
+        success: true,
+        deliverable,
+        jobId: String(jobId),
+      };
+    }
 
     return {
-      success: true,
+      success: finalPhase === "COMPLETED",
       deliverable: {
         type: "acp-escrow",
-        jobId: jobData.jobId ?? jobData.id,
-        status: "created",
-        message: "ACP escrow job created with ERC-8183. Agent will process and deliver.",
+        jobId: String(jobId),
+        phase: finalPhase,
+        message: finalPhase === "COMPLETED" ? "Job completed" : `Job ended with phase: ${finalPhase}`,
         offering: offering.name,
         price: offering.price,
         agent: agent.name,
+        deliverable,
       },
-      jobId: String(jobData.jobId ?? jobData.id),
+      jobId: String(jobId),
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);

package/src/wallet/handlers/l402.ts

@@ -7,6 +7,7 @@
 import { fetchWithL402, type KVStorage } from "@getalby/lightning-tools/l402";
 import type { KompassWallet } from "../index.js";
 import type { UnifiedAgent } from "../../sources/types.js";
+import { swapUSDCtoLightning } from "../bridge.js";
 
 // In-memory token storage for L402 macaroons
 class L402Store implements KVStorage {

package/src/wallet/index.ts

@@ -13,7 +13,8 @@ import { homedir } from "os";
 import { join } from "path";
 
 const DEFAULT_WALLET_PATH = join(homedir(), ".kompass", "wallet.json");
-const DEFAULT_PASSWORD = "kompass-agent"; // TODO: prompt user for password in production
+const DEFAULT_PASSWORD = "kompass-agent";
+const DEFAULT_NETWORK: "base" | "base-sepolia" = "base"; // Mainnet by default
 
 const ERC20_ABI = [
   { type: "function", name: "balanceOf", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }], stateMutability: "view" },
@@ -52,7 +53,7 @@ export class KompassWallet {
    */
   static create(options?: { path?: string; network?: "base" | "base-sepolia"; password?: string }): KompassWallet {
     const path = options?.path ?? DEFAULT_WALLET_PATH;
-    const network = options?.network ?? "base-sepolia";
+    const network = options?.network ?? DEFAULT_NETWORK;
     const password = options?.password ?? DEFAULT_PASSWORD;
 
     const privateKey = generatePrivateKey();

package/src/wallet/payment-router.ts

@@ -11,6 +11,7 @@ import { handleL402Payment } from "./handlers/l402.js";
 import { handleMPPPayment } from "./handlers/mpp.js";
 import { handleNanopayment } from "./handlers/nanopayments.js";
 import { handleFreePayment } from "./handlers/free.js";
+import { ensureSufficientBalance } from "./bridge.js";
 
 export interface PaymentResult {
   success: boolean;
@@ -31,6 +32,20 @@ export async function routePayment(
   const protocol = determinePaymentProtocol(agent);
 
   try {
+    // Pre-payment: ensure wallet has enough funds (skip for free)
+    if (protocol !== "free") {
+      const estimatedCost = parseFloat(agent.pricing?.amount ?? "0.05");
+      try {
+        await ensureSufficientBalance(wallet, estimatedCost);
+      } catch (balErr) {
+        return {
+          success: false,
+          protocol,
+          error: balErr instanceof Error ? balErr.message : String(balErr),
+        };
+      }
+    }
+
     switch (protocol) {
       case "x402": {
         const result = await handleX402Payment(wallet, agent, task);