kompass-sdk 0.1.0

package/src/index.ts

@@ -0,0 +1,245 @@
+import { formatUnits, formatEther, type Address, type Hex } from "viem";
+import type {
+  KompassConfig,
+  AgentProfile,
+  CreateJobOptions,
+  CreateJobResult,
+  DiscoverOptions,
+  Job,
+  MilestoneData,
+  PaymentMode,
+  RegisterProfile,
+  ReputationSummary,
+  TxResult,
+} from "./types.js";
+import type { AgentCapabilityRole, IntentRoute, YieldIntent } from "./intents.js";
+import type {
+  X402ClientOptions,
+  X402PaymentRequestContext,
+  X402PaymentRequirement,
+  X402PaymentResponse,
+} from "./x402.js";
+import { discover, getAgent, findEvaluator } from "./discover.js";
+import { createJob, setBudget, fund, submit, complete, completePartial, reject, getJob, getMilestones } from "./escrow.js";
+import { register, updateProfile, deregister } from "./registry.js";
+import { getReputation } from "./reputation.js";
+import { routeYieldIntent } from "./intents.js";
+import { parseX402Requirement, requestWithX402 } from "./x402.js";
+import { buildYieldPipelinePlan, createYieldPipeline } from "./pipelines.js";
+
+export class Kompass {
+  private config: KompassConfig;
+
+  constructor(config: KompassConfig) {
+    this.config = config;
+  }
+
+  // ── Discovery ──────────────────────────────────────
+
+  async discover(options?: DiscoverOptions): Promise<AgentProfile[]> {
+    return discover(this.config, options);
+  }
+
+  async getAgent(address: string): Promise<AgentProfile | null> {
+    return getAgent(this.config, address);
+  }
+
+  async findEvaluator(domain: string): Promise<AgentProfile[]> {
+    return findEvaluator(this.config, domain);
+  }
+
+  async routeYieldIntent(intent: YieldIntent, options?: DiscoverOptions): Promise<IntentRoute> {
+    const agents = await discover(this.config, {
+      verifiedOnly: true,
+      ...options,
+    });
+    return routeYieldIntent(agents, intent);
+  }
+
+  async requestWithX402(url: string, init: RequestInit, options: X402ClientOptions): Promise<Response> {
+    return requestWithX402(url, init, options);
+  }
+
+  buildYieldPipelinePlan(route: IntentRoute) {
+    const token = this.config.paymentTokenAddress;
+    if (!token) {
+      throw new Error("paymentTokenAddress is required in KompassConfig");
+    }
+    return buildYieldPipelinePlan(route, { token });
+  }
+
+  async createYieldPipeline(route: IntentRoute) {
+    return createYieldPipeline(this.config, route);
+  }
+
+  // ── Escrow ─────────────────────────────────────────
+
+  async createJob(options: CreateJobOptions): Promise<CreateJobResult> {
+    return createJob(this.config, options);
+  }
+
+  async setBudget(jobId: bigint, amount: bigint): Promise<TxResult> {
+    return setBudget(this.config, jobId, amount);
+  }
+
+  async fund(jobId: bigint): Promise<TxResult> {
+    return fund(this.config, jobId);
+  }
+
+  async submit(jobId: bigint, deliverable: Hex, milestoneIndex?: number): Promise<TxResult> {
+    return submit(this.config, jobId, deliverable, milestoneIndex);
+  }
+
+  async complete(jobId: bigint, reason?: Hex, milestoneIndex?: number): Promise<TxResult> {
+    return complete(this.config, jobId, reason, milestoneIndex);
+  }
+
+  async completePartial(jobId: bigint, percentageBps: number, reason?: Hex): Promise<TxResult> {
+    return completePartial(this.config, jobId, percentageBps, reason);
+  }
+
+  async reject(jobId: bigint, reason?: Hex): Promise<TxResult> {
+    return reject(this.config, jobId, reason);
+  }
+
+  async getJob(jobId: bigint): Promise<Job> {
+    return getJob(this.config, jobId);
+  }
+
+  async getMilestones(jobId: bigint): Promise<MilestoneData[]> {
+    return getMilestones(this.config, jobId);
+  }
+
+  // ── Registry ───────────────────────────────────────
+
+  async register(profile: RegisterProfile): Promise<TxResult> {
+    return register(this.config, profile);
+  }
+
+  async updateProfile(ensNode: Hex, updates: Partial<Omit<RegisterProfile, "ensNode">>): Promise<TxResult> {
+    return updateProfile(this.config, ensNode, updates);
+  }
+
+  async deregister(): Promise<TxResult> {
+    return deregister(this.config);
+  }
+
+  // ── Reputation ─────────────────────────────────────
+
+  async getReputation(agentId: bigint, tag1?: string, tag2?: string): Promise<ReputationSummary> {
+    return getReputation(this.config, agentId, tag1, tag2);
+  }
+
+  // ── Token Operations ─────────────────────────────────
+
+  async approveToken(spender: Address, amount: bigint): Promise<TxResult> {
+    if (!this.config.walletClient) throw new Error("WalletClient required for approveToken");
+    const tokenAddress = this.config.paymentTokenAddress;
+    if (!tokenAddress) throw new Error("paymentTokenAddress required in KompassConfig");
+
+    const txHash = await this.config.walletClient.writeContract({
+      address: tokenAddress,
+      abi: [{ type: "function", name: "approve", inputs: [{ name: "spender", type: "address" }, { name: "value", type: "uint256" }], outputs: [{ name: "", type: "bool" }], stateMutability: "nonpayable" }] as const,
+      functionName: "approve",
+      args: [spender, amount],
+    });
+    await this.config.publicClient.waitForTransactionReceipt({ hash: txHash });
+    return { txHash };
+  }
+
+  async getBalance(): Promise<{ address: Address; eth: string; usdc: string; usdcRaw: string; ethRaw: string }> {
+    const address = this.config.walletClient?.account?.address;
+    if (!address) throw new Error("WalletClient required for getBalance");
+
+    const ethBalance = await this.config.publicClient.getBalance({ address });
+    let usdcBalance = 0n;
+
+    if (this.config.paymentTokenAddress) {
+      usdcBalance = await this.config.publicClient.readContract({
+        address: this.config.paymentTokenAddress,
+        abi: [{ type: "function", name: "balanceOf", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }], stateMutability: "view" }] as const,
+        functionName: "balanceOf",
+        args: [address],
+      });
+    }
+
+    return {
+      address,
+      eth: formatEther(ethBalance),
+      usdc: formatUnits(usdcBalance, 6),
+      usdcRaw: usdcBalance.toString(),
+      ethRaw: ethBalance.toString(),
+    };
+  }
+}
+
+// Re-export everything for direct usage
+export type {
+  KompassConfig,
+  AgentProfile,
+  AgentType,
+  PaymentMode,
+  CreateJobOptions,
+  CreateJobResult,
+  DiscoverOptions,
+  Job,
+  JobStatus,
+  MilestoneConfig,
+  MilestoneData,
+  MilestoneStatus,
+  RegisterProfile,
+  ReputationSummary,
+  TxResult,
+} from "./types.js";
+
+export type {
+  AgentCapabilityRole,
+  IntentRoute,
+  YieldIntent,
+} from "./intents.js";
+
+export type {
+  X402ClientOptions,
+  X402PaymentRequestContext,
+  X402PaymentRequirement,
+  X402PaymentResponse,
+} from "./x402.js";
+
+export type {
+  CreatePipelineOptions,
+  CreatePipelineResult,
+  PipelineSettlementMode,
+  YieldPipelinePlan,
+  YieldPipelineSubtask,
+} from "./pipelines.js";
+
+export { discover, getAgent, findEvaluator } from "./discover.js";
+export { createJob, setBudget, fund, submit, complete, completePartial, reject, getJob, getMilestones } from "./escrow.js";
+export { register, updateProfile, deregister, computeENSIP25Key, setENSIP25Record } from "./registry.js";
+export { getReputation } from "./reputation.js";
+export { routeYieldIntent } from "./intents.js";
+export { parseX402Requirement, requestWithX402 } from "./x402.js";
+export { buildYieldPipelinePlan, createYieldPipeline } from "./pipelines.js";
+
+// Framework adapters
+export * as adapters from "./adapters/index.js";
+
+// Simplified API (Kompass intelligence layer on top of ACP)
+export { KompassSimple } from "./simple.js";
+export type { KompassSimpleConfig, HireOptions, HireResult, AcceptJobsOptions, OrchestrateOptions, OrchestrateResult } from "./simple.js";
+
+// Backend adapters
+export { AcpEscrowBackend } from "./backends/acp.js";
+export type { EscrowBackend, AgentSearchResult, AgentOffering, JobResult, IncomingJob } from "./backends/types.js";
+
+// Universal Discovery (Kompass v2 — cross-protocol)
+export { KompassUnified } from "./unified.js";
+export type { UnifiedConfig, FindOptions, FindResult } from "./unified.js";
+export { Aggregator } from "./aggregator.js";
+export { rankAgents } from "./matching.js";
+export { ProtocolBridge } from "./bridge.js";
+export type { BridgeHireOptions, BridgeHireResult } from "./bridge.js";
+export { CapabilityRouter } from "./router.js";
+export type { DoOptions, DoResult, CapabilityOption, CostPreference } from "./router.js";
+export { createAllSources } from "./sources/index.js";
+export type { UnifiedAgent, AgentSource, AgentProtocol, SourceAdapter } from "./sources/types.js";

package/src/intents.ts

@@ -0,0 +1,166 @@
+import type { AgentProfile, PaymentMode } from "./types.js";
+
+export type YieldRiskTolerance = "conservative" | "balanced" | "aggressive";
+export type YieldObjective = "best-yield" | "best-risk-adjusted";
+export type AgentCapabilityRole = "research" | "premium-data" | "risk" | "execution";
+
+export interface YieldIntent {
+  amount: bigint;
+  riskTolerance: YieldRiskTolerance;
+  objective?: YieldObjective;
+  stablecoin?: string;
+  chain?: string;
+}
+
+export interface RouteStep {
+  role: AgentCapabilityRole;
+  title: string;
+  summary: string;
+  requiredPaymentMode: PaymentMode | "any";
+  categories: string[];
+  agent: AgentProfile | null;
+}
+
+export interface IntentRoute {
+  intent: YieldIntent;
+  steps: RouteStep[];
+  recommendedAgents: AgentProfile[];
+  missingCapabilities: AgentCapabilityRole[];
+  summary: string;
+}
+
+const ROLE_CONFIG: Record<
+  AgentCapabilityRole,
+  {
+    title: string;
+    summary: string;
+    categories: string[];
+    requiredPaymentMode: PaymentMode | "any";
+    preferredType?: AgentProfile["agentType"];
+  }
+> = {
+  research: {
+    title: "Research",
+    summary: "Find candidate Base strategies and estimate raw yield.",
+    categories: ["defi", "analytics", "research", "yield"],
+    requiredPaymentMode: "any",
+    preferredType: "provider",
+  },
+  "premium-data": {
+    title: "Premium Data",
+    summary: "Buy market, protocol, or yield data over x402.",
+    categories: ["data", "analytics", "signals"],
+    requiredPaymentMode: "x402",
+    preferredType: "provider",
+  },
+  risk: {
+    title: "Risk Review",
+    summary: "Evaluate strategy safety, policy fit, and execution readiness.",
+    categories: ["risk", "security", "defi"],
+    requiredPaymentMode: "any",
+    preferredType: "evaluator",
+  },
+  execution: {
+    title: "Execution",
+    summary: "Prepare or submit the final Base execution plan.",
+    categories: ["yield", "swap", "bridge", "defi"],
+    requiredPaymentMode: "escrow",
+    preferredType: "provider",
+  },
+};
+
+function parseCategories(value: string): string[] {
+  return value
+    .split(",")
+    .map((item) => item.trim().toLowerCase())
+    .filter(Boolean);
+}
+
+function scoreAgent(agent: AgentProfile, role: AgentCapabilityRole): number {
+  const config = ROLE_CONFIG[role];
+  const categories = parseCategories(agent.categories);
+  let score = 0;
+
+  for (const category of config.categories) {
+    if (categories.includes(category)) {
+      score += 3;
+    }
+  }
+
+  if (config.preferredType && (agent.agentType === config.preferredType || agent.agentType === "both")) {
+    score += 3;
+  }
+
+  if (agent.identityVerified) {
+    score += 2;
+  }
+
+  if (config.requiredPaymentMode === "x402" && agent.x402Enabled) {
+    score += 4;
+  }
+
+  if (config.requiredPaymentMode === "escrow" && (agent.paymentMode === "escrow" || agent.paymentMode === "hybrid")) {
+    score += 2;
+  }
+
+  if (agent.paymentMode === "hybrid") {
+    score += 1;
+  }
+
+  return score;
+}
+
+function supportsPaymentMode(agent: AgentProfile, required: PaymentMode | "any"): boolean {
+  if (required === "any") return true;
+  if (required === "x402") {
+    return agent.x402Enabled || agent.paymentMode === "x402" || agent.paymentMode === "hybrid";
+  }
+  if (required === "escrow") {
+    return agent.paymentMode === "escrow" || agent.paymentMode === "hybrid";
+  }
+  return agent.paymentMode === required;
+}
+
+function selectBestAgent(agents: AgentProfile[], role: AgentCapabilityRole): AgentProfile | null {
+  const candidates = agents
+    .filter((agent) => supportsPaymentMode(agent, ROLE_CONFIG[role].requiredPaymentMode))
+    .map((agent) => ({ agent, score: scoreAgent(agent, role) }))
+    .filter((entry) => entry.score > 0)
+    .sort((a, b) => b.score - a.score);
+
+  return candidates[0]?.agent ?? null;
+}
+
+export function routeYieldIntent(agents: AgentProfile[], intent: YieldIntent): IntentRoute {
+  const orderedRoles: AgentCapabilityRole[] = ["research", "premium-data", "risk", "execution"];
+  const steps = orderedRoles.map((role) => {
+    const config = ROLE_CONFIG[role];
+    return {
+      role,
+      title: config.title,
+      summary: config.summary,
+      requiredPaymentMode: config.requiredPaymentMode,
+      categories: config.categories,
+      agent: selectBestAgent(agents, role),
+    };
+  });
+
+  const missingCapabilities = steps
+    .filter((step) => !step.agent)
+    .map((step) => step.role);
+
+  const recommendedAgents = steps
+    .map((step) => step.agent)
+    .filter((agent): agent is AgentProfile => agent !== null);
+
+  const stablecoin = intent.stablecoin ?? "USDC";
+  const objective = intent.objective ?? "best-risk-adjusted";
+
+  return {
+    intent,
+    steps,
+    recommendedAgents,
+    missingCapabilities,
+    summary: `Route ${stablecoin} capital on ${intent.chain ?? "Base"} for ${objective} yield using ${recommendedAgents.length} discovered agents.`,
+  };
+}

package/src/matching.ts

@@ -0,0 +1,192 @@
+/**
+ * Kompass Multi-Layer Agent Matching
+ *
+ * Layer A: Structured capability matching (ontology-style)
+ * Layer B: BM25 text relevance scoring
+ * Layer C: LLM re-ranking (optional, for top candidates)
+ * Layer D: Multi-criteria scoring (reputation, price, protocol, recency)
+ */
+
+import type { UnifiedAgent } from "./sources/types.js";
+
+// ── Layer A: Structured Capability Matching ──────────────
+
+interface ParsedIntent {
+  domain: string | null;
+  actions: string[];
+  protocols: string[];
+  chains: string[];
+  priceMax: number | null;
+}
+
+const DOMAIN_KEYWORDS: Record<string, string[]> = {
+  defi: ["defi", "yield", "swap", "liquidity", "pool", "lending", "borrow", "stake", "vault", "farm"],
+  data: ["data", "analytics", "research", "market", "price", "chart", "feed", "api"],
+  trading: ["trade", "trading", "buy", "sell", "order", "exchange", "dex", "cex"],
+  risk: ["risk", "audit", "security", "vulnerability", "safe", "score"],
+  content: ["content", "write", "generate", "image", "video", "text", "create"],
+  development: ["code", "develop", "build", "deploy", "smart contract", "solidity"],
+  ai: ["ai", "llm", "model", "inference", "embedding", "prompt"],
+  social: ["social", "twitter", "post", "tweet", "farcaster"],
+};
+
+const PROTOCOL_KEYWORDS: Record<string, string[]> = {
+  x402: ["x402", "micropayment", "http 402", "pay per call"],
+  acp: ["acp", "virtuals", "escrow", "marketplace"],
+  mcp: ["mcp", "tool", "server", "model context"],
+  a2a: ["a2a", "agent to agent", "google"],
+  l402: ["l402", "lightning", "bitcoin", "sats"],
+};
+
+const CHAIN_KEYWORDS: Record<string, string[]> = {
+  base: ["base", "coinbase"],
+  ethereum: ["ethereum", "eth", "mainnet"],
+  solana: ["solana", "sol"],
+  bnb: ["bnb", "bsc", "binance"],
+  arbitrum: ["arbitrum", "arb"],
+  polygon: ["polygon", "matic"],
+};
+
+function parseIntent(query: string): ParsedIntent {
+  const lower = query.toLowerCase();
+
+  let domain: string | null = null;
+  for (const [d, keywords] of Object.entries(DOMAIN_KEYWORDS)) {
+    if (keywords.some((k) => lower.includes(k))) {
+      domain = d;
+      break;
+    }
+  }
+
+  const actions = Object.entries(DOMAIN_KEYWORDS)
+    .flatMap(([, keywords]) => keywords.filter((k) => lower.includes(k)));
+
+  const protocols = Object.entries(PROTOCOL_KEYWORDS)
+    .filter(([, keywords]) => keywords.some((k) => lower.includes(k)))
+    .map(([p]) => p);
+
+  const chains = Object.entries(CHAIN_KEYWORDS)
+    .filter(([, keywords]) => keywords.some((k) => lower.includes(k)))
+    .map(([c]) => c);
+
+  const priceMatch = lower.match(/under\s*\$?(\d+(?:\.\d+)?)/);
+  const priceMax = priceMatch ? parseFloat(priceMatch[1]) : null;
+
+  return { domain, actions, protocols, chains, priceMax };
+}
+
+function structuredScore(agent: UnifiedAgent, intent: ParsedIntent): number {
+  let score = 0;
+
+  // Domain match
+  if (intent.domain && agent.categories.includes(intent.domain)) score += 15;
+
+  // Action keyword matches
+  const agentText = `${agent.name} ${agent.description} ${agent.categories.join(" ")}`.toLowerCase();
+  for (const action of intent.actions) {
+    if (agentText.includes(action)) score += 3;
+  }
+
+  // Protocol match
+  if (intent.protocols.length > 0) {
+    if (intent.protocols.includes(agent.protocol)) score += 20;
+  }
+
+  // Price filter
+  if (intent.priceMax && agent.pricing?.amount) {
+    const price = parseFloat(agent.pricing.amount);
+    if (price <= intent.priceMax) score += 10;
+    else score -= 10; // Penalize over budget
+  }
+
+  return score;
+}
+
+// ── Layer B: BM25-lite Text Relevance ────────────────────
+
+function bm25Score(agent: UnifiedAgent, queryTerms: string[]): number {
+  const doc = `${agent.name} ${agent.description} ${agent.categories.join(" ")} ${agent.capabilities.join(" ")}`.toLowerCase();
+  const docTerms = doc.split(/\s+/);
+  const docLen = docTerms.length;
+  const avgDocLen = 50; // Approximate average
+  const k1 = 1.5;
+  const b = 0.75;
+
+  let score = 0;
+  for (const term of queryTerms) {
+    const tf = docTerms.filter((t) => t.includes(term)).length;
+    if (tf === 0) continue;
+
+    // Simplified BM25
+    const numerator = tf * (k1 + 1);
+    const denominator = tf + k1 * (1 - b + b * (docLen / avgDocLen));
+    score += numerator / denominator;
+  }
+
+  return score * 10; // Scale up
+}
+
+// ── Layer D: Multi-Criteria Scoring ──────────────────────
+
+function multiCriteriaScore(agent: UnifiedAgent): number {
+  let score = 0;
+
+  // Reputation
+  if (agent.reputation) {
+    score += Math.min(agent.reputation.score * 0.2, 20);
+    score += Math.min(agent.reputation.count * 0.5, 10);
+  }
+
+  // Verified identity
+  if (agent.verified) score += 5;
+
+  // Pricing transparency
+  if (agent.pricing && agent.pricing.model !== "unknown") score += 3;
+
+  // Endpoint richness (more protocols = more interoperable)
+  const endpointCount = Object.values(agent.endpoints).filter(Boolean).length;
+  score += endpointCount * 2;
+
+  // Recency
+  if (agent.lastSeen) {
+    const hoursSince = (Date.now() - agent.lastSeen) / (1000 * 60 * 60);
+    if (hoursSince < 1) score += 5;
+    else if (hoursSince < 24) score += 3;
+    else if (hoursSince < 168) score += 1;
+  }
+
+  return score;
+}
+
+// ── Combined Ranking Pipeline ────────────────────────────
+
+export interface MatchResult {
+  agent: UnifiedAgent;
+  scores: {
+    structured: number;
+    bm25: number;
+    multiCriteria: number;
+    total: number;
+  };
+}
+
+export function rankAgents(agents: UnifiedAgent[], query: string): MatchResult[] {
+  const intent = parseIntent(query);
+  const queryTerms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 2);
+
+  return agents
+    .map((agent) => {
+      const structured = structuredScore(agent, intent);
+      const bm25 = bm25Score(agent, queryTerms);
+      const multi = multiCriteriaScore(agent);
+      const total = structured + bm25 + multi;
+
+      return {
+        agent,
+        scores: { structured, bm25, multiCriteria: multi, total },
+      };
+    })
+    .sort((a, b) => b.scores.total - a.scores.total);
+}
+
+export { parseIntent, type ParsedIntent };

package/src/pipelineAbi.ts

@@ -0,0 +1,74 @@
+export const PipelineOrchestratorAbi = [
+  {
+    type: "event",
+    name: "PipelineCreated",
+    anonymous: false,
+    inputs: [
+      { indexed: true, name: "pipelineId", type: "uint256" },
+      { indexed: true, name: "client", type: "address" },
+      { indexed: false, name: "intentHash", type: "bytes32" },
+    ],
+  },
+  {
+    type: "function",
+    name: "createPipeline",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "token", type: "address" },
+      { name: "intentHash", type: "bytes32" },
+    ],
+    outputs: [{ name: "pipelineId", type: "uint256" }],
+  },
+  {
+    type: "function",
+    name: "createPipelineWithHook",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "token", type: "address" },
+      { name: "intentHash", type: "bytes32" },
+      { name: "defaultHook", type: "address" },
+    ],
+    outputs: [{ name: "pipelineId", type: "uint256" }],
+  },
+  {
+    type: "function",
+    name: "addSubTask",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "pipelineId", type: "uint256" },
+      { name: "provider", type: "address" },
+      { name: "evaluator", type: "address" },
+      { name: "budget", type: "uint256" },
+      { name: "descriptionHash", type: "bytes32" },
+      { name: "dependencies", type: "uint256[]" },
+    ],
+    outputs: [{ name: "subTaskIndex", type: "uint256" }],
+  },
+  {
+    type: "function",
+    name: "fundPipeline",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "pipelineId", type: "uint256" }],
+    outputs: [],
+  },
+  {
+    type: "function",
+    name: "activateNextTasks",
+    stateMutability: "nonpayable",
+    inputs: [{ name: "pipelineId", type: "uint256" }],
+    outputs: [],
+  },
+] as const;
+
+export const Erc20ApproveAbi = [
+  {
+    type: "function",
+    name: "approve",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "value", type: "uint256" },
+    ],
+    outputs: [{ name: "", type: "bool" }],
+  },
+] as const;