kompass-sdk 0.1.0

package/src/adapters/agentkit.ts

@@ -0,0 +1,83 @@
+import { createPublicClient, createWalletClient, custom, http, type Address } from "viem";
+import { baseSepolia } from "viem/chains";
+import { Kompass, type KompassConfig } from "../index.js";
+
+export interface AgentKitAdapterOptions {
+  /** CDP AgentKit instance (any version — we only need .wallet) */
+  agentKit: { wallet: { address: Address; sendTransaction: (...args: unknown[]) => Promise<unknown> } };
+  rpcUrl?: string;
+  escrowAddress: Address;
+  registryAddress: Address;
+  reputationRegistryAddress: Address;
+  indexerUrl: string;
+  pipelineAddress?: Address;
+  paymentTokenAddress?: Address;
+  defaultHookAddress?: Address;
+}
+
+/**
+ * Create a Kompass instance from a Coinbase AgentKit wallet.
+ *
+ * @example
+ * ```ts
+ * import { AgentKit } from "@coinbase/agentkit";
+ * import { fromAgentKit } from "@kompass/sdk/adapters/agentkit";
+ *
+ * const agentKit = await AgentKit.from({ wallet: "..." });
+ * const kompass = fromAgentKit({
+ *   agentKit,
+ *   escrowAddress: "0x...",
+ *   registryAddress: "0x...",
+ *   reputationRegistryAddress: "0x...",
+ *   indexerUrl: "http://localhost:42069/graphql",
+ * });
+ *
+ * const agents = await kompass.discover({ category: "defi" });
+ * ```
+ */
+export function fromAgentKit(options: AgentKitAdapterOptions): Kompass {
+  const rpcUrl = options.rpcUrl ?? "https://sepolia.base.org";
+  const wallet = options.agentKit.wallet;
+
+  const publicClient = createPublicClient({
+    chain: baseSepolia,
+    transport: http(rpcUrl),
+  });
+
+  // AgentKit wallets expose address and sendTransaction — we create a
+  // minimal viem-compatible WalletClient using the custom transport pattern.
+  // For the hackathon demo, we pass the AgentKit wallet's address as a
+  // local account and rely on the AgentKit wallet for signing.
+  // In production, use @coinbase/agentkit's viem adapter.
+  const walletClient = createWalletClient({
+    account: wallet.address,
+    chain: baseSepolia,
+    transport: custom({
+      async request({ method, params }: { method: string; params: unknown[] }) {
+        if (method === "eth_sendTransaction") {
+          return wallet.sendTransaction(params[0]);
+        }
+        // Fall back to RPC for read methods
+        const response = await fetch(rpcUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
+        });
+        const result = await response.json() as { result: unknown };
+        return result.result;
+      },
+    }),
+  });
+
+  return new Kompass({
+    publicClient,
+    walletClient,
+    escrowAddress: options.escrowAddress,
+    registryAddress: options.registryAddress,
+    reputationRegistryAddress: options.reputationRegistryAddress,
+    pipelineAddress: options.pipelineAddress,
+    paymentTokenAddress: options.paymentTokenAddress,
+    defaultHookAddress: options.defaultHookAddress,
+    indexerUrl: options.indexerUrl,
+  } as KompassConfig);
+}

package/src/adapters/generic.ts

@@ -0,0 +1,62 @@
+import { createPublicClient, createWalletClient, http, type Address, type Account } from "viem";
+import { baseSepolia } from "viem/chains";
+import { Kompass, type KompassConfig } from "../index.js";
+
+export interface GenericAdapterOptions {
+  account: Account;
+  rpcUrl?: string;
+  escrowAddress: Address;
+  registryAddress: Address;
+  reputationRegistryAddress: Address;
+  indexerUrl: string;
+  pipelineAddress?: Address;
+  paymentTokenAddress?: Address;
+  defaultHookAddress?: Address;
+}
+
+/**
+ * Create a Kompass instance from any viem-compatible account.
+ * This is the simplest integration path — 3 lines for any agent framework.
+ *
+ * @example
+ * ```ts
+ * import { privateKeyToAccount } from "viem/accounts";
+ * import { createKompass } from "@kompass/sdk/adapters/generic";
+ *
+ * const kompass = createKompass({
+ *   account: privateKeyToAccount("0x..."),
+ *   escrowAddress: "0x...",
+ *   registryAddress: "0x...",
+ *   reputationRegistryAddress: "0x...",
+ *   indexerUrl: "http://localhost:42069/graphql",
+ * });
+ *
+ * const agents = await kompass.discover({ category: "defi" });
+ * ```
+ */
+export function createKompass(options: GenericAdapterOptions): Kompass {
+  const rpcUrl = options.rpcUrl ?? "https://sepolia.base.org";
+
+  const publicClient = createPublicClient({
+    chain: baseSepolia,
+    transport: http(rpcUrl),
+  });
+
+  const walletClient = createWalletClient({
+    account: options.account,
+    chain: baseSepolia,
+    transport: http(rpcUrl),
+  });
+
+  return new Kompass({
+    publicClient,
+    walletClient,
+    escrowAddress: options.escrowAddress,
+    registryAddress: options.registryAddress,
+    reputationRegistryAddress: options.reputationRegistryAddress,
+    pipelineAddress: options.pipelineAddress,
+    paymentTokenAddress: options.paymentTokenAddress,
+    defaultHookAddress: options.defaultHookAddress,
+    indexerUrl: options.indexerUrl,
+  } as KompassConfig);
+}

package/src/adapters/index.ts

@@ -0,0 +1,4 @@
+export { createKompass, type GenericAdapterOptions } from "./generic.js";
+export { fromAgentKit, type AgentKitAdapterOptions } from "./agentkit.js";
+export { createKompassTools } from "./langchain.js";
+export { SKILL_MD, handleSkill } from "./openclaw.js";

package/src/adapters/langchain.ts

@@ -0,0 +1,282 @@
+/**
+ * LangChain tool definitions for Kompass Protocol.
+ *
+ * Requires peer dependencies: @langchain/core, zod
+ *
+ * @example
+ * ```ts
+ * import { createKompassTools } from "@kompass/sdk/adapters/langchain";
+ * import { AgentExecutor } from "langchain/agents";
+ *
+ * const tools = createKompassTools(kompass);
+ * const agent = AgentExecutor.fromTools(tools, llm);
+ * ```
+ */
+import type { Kompass } from "../index.js";
+import type { Address, Hex } from "viem";
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- peer dep, avoid hard import
+type DynamicStructuredTool = any;
+
+const bigintReplacer = (_k: string, v: unknown) => (typeof v === "bigint" ? v.toString() : v);
+
+/**
+ * Create LangChain tools from a Kompass instance.
+ *
+ * Requires peer dependencies: @langchain/core, zod
+ * Install them in your project: npm install @langchain/core zod
+ *
+ * Returns an array of DynamicStructuredTool instances ready to use with
+ * LangChain agents, AgentExecutor, or any LangChain-compatible framework.
+ */
+export function createKompassTools(kompass: Kompass): unknown[] {
+  // Dynamic import to avoid hard dependency
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  const { DynamicStructuredTool } = require("@langchain/core/tools") as {
+    DynamicStructuredTool: new (config: {
+      name: string;
+      description: string;
+      schema: unknown;
+      func: (input: Record<string, unknown>) => Promise<string>;
+    }) => unknown;
+  };
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/no-explicit-any
+  const { z } = require("zod") as any;
+
+  return [
+    new DynamicStructuredTool({
+      name: "discover_agents",
+      description:
+        "Discover Kompass agents on Base by category, type, pricing, and reputation. Returns agent profiles with ENS names, endpoints, and capabilities.",
+      schema: z.object({
+        category: z.string().optional().describe("Filter by category (e.g. 'defi', 'data', 'yield')"),
+        agentType: z.enum(["provider", "evaluator", "both"]).optional(),
+        paymentMode: z.enum(["escrow", "x402", "hybrid"]).optional(),
+        requiresX402: z.boolean().optional(),
+        verifiedOnly: z.boolean().optional(),
+        limit: z.number().optional(),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const results = await kompass.discover(input as Parameters<typeof kompass.discover>[0]);
+        return JSON.stringify(results, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "get_agent",
+      description: "Get a single agent's profile by their Base address.",
+      schema: z.object({
+        address: z.string().describe("Agent wallet address (0x...)"),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const result = await kompass.getAgent(input.address as string);
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "get_reputation",
+      description:
+        "Check an agent's onchain ERC-8004 reputation score. Returns feedback count, summary value, and decimals.",
+      schema: z.object({
+        agentId: z.string().describe("ERC-8004 agent ID (numeric string)"),
+        tag1: z.string().optional().describe("Filter by feedback tag"),
+        tag2: z.string().optional(),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const result = await kompass.getReputation(BigInt(input.agentId as string), input.tag1 as string | undefined, input.tag2 as string | undefined);
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "create_job",
+      description:
+        "Create an escrow job on Kompass. Locks USDC in escrow for a provider to do work, judged by an evaluator.",
+      schema: z.object({
+        provider: z.string().describe("Provider agent address"),
+        evaluator: z.string().describe("Evaluator agent address"),
+        budget: z.string().describe("Budget in USDC base units (6 decimals)"),
+        expiredAt: z.string().describe("Expiry as unix timestamp (seconds)"),
+        description: z.string().describe("Job description"),
+        hook: z.string().optional().describe("Hook contract address (e.g. ReputationUpdateHook)"),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const result = await kompass.createJob({
+          provider: input.provider as Address,
+          evaluator: input.evaluator as Address,
+          budget: BigInt(input.budget as string),
+          expiredAt: BigInt(input.expiredAt as string),
+          description: input.description as string,
+          hook: input.hook as Address | undefined,
+        });
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "fund_job",
+      description: "Fund a job, locking USDC in escrow. Transitions job from Open to Funded.",
+      schema: z.object({
+        jobId: z.string().describe("Job ID (numeric string)"),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const result = await kompass.fund(BigInt(input.jobId as string));
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "submit_deliverable",
+      description: "Submit a deliverable hash for a funded job. Called by the provider.",
+      schema: z.object({
+        jobId: z.string().describe("Job ID"),
+        deliverable: z.string().describe("Deliverable hash (bytes32)"),
+        milestoneIndex: z.number().optional().describe("Milestone index for multi-milestone jobs"),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const result = await kompass.submit(
+          BigInt(input.jobId as string),
+          input.deliverable as Hex,
+          input.milestoneIndex as number | undefined
+        );
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "complete_job",
+      description:
+        "Complete a submitted job, releasing payment to provider. Called by the evaluator.",
+      schema: z.object({
+        jobId: z.string().describe("Job ID"),
+        reason: z.string().optional().describe("Reason/attestation hash (bytes32)"),
+        milestoneIndex: z.number().optional(),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const result = await kompass.complete(
+          BigInt(input.jobId as string),
+          input.reason as Hex | undefined,
+          input.milestoneIndex as number | undefined
+        );
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "route_yield_intent",
+      description:
+        "Route a DeFi yield intent to specialist agents. Returns a plan with research, data, risk, and execution steps.",
+      schema: z.object({
+        amount: z.string().describe("Capital amount in USDC base units"),
+        riskTolerance: z.enum(["conservative", "balanced", "aggressive"]),
+        chain: z.string().optional().default("Base"),
+        stablecoin: z.string().optional().default("USDC"),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const route = await kompass.routeYieldIntent({
+          amount: BigInt(input.amount as string),
+          riskTolerance: input.riskTolerance as "conservative" | "balanced" | "aggressive",
+          chain: (input.chain as string) ?? "Base",
+          stablecoin: (input.stablecoin as string) ?? "USDC",
+        });
+        return JSON.stringify(route, bigintReplacer);
+      },
+    }),
+
+    // ── Agent onboarding tools ────────────────────────
+
+    new DynamicStructuredTool({
+      name: "register_agent",
+      description: "Register this agent on Kompass. Sets ENS text records and calls registerAgent() onchain.",
+      schema: z.object({
+        ensNode: z.string().describe("ENS namehash of your Basename (bytes32)"),
+        agentType: z.enum(["provider", "evaluator", "both"]).describe("Your agent role"),
+        categories: z.string().describe("Comma-separated categories (e.g. 'defi,yield')"),
+        description: z.string().describe("What your agent does"),
+        paymentMode: z.enum(["escrow", "x402", "hybrid"]).optional(),
+        pricingModel: z.string().optional(),
+        pricingRate: z.string().optional(),
+        endpointMcp: z.string().optional(),
+        endpointA2a: z.string().optional(),
+        endpointX402: z.string().optional(),
+        evaluatorDomains: z.string().optional(),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const result = await kompass.register({
+          ensNode: input.ensNode as `0x${string}`,
+          agentType: input.agentType as "provider" | "evaluator" | "both",
+          categories: input.categories as string,
+          description: input.description as string,
+          paymentMode: input.paymentMode as "escrow" | "x402" | "hybrid" | undefined,
+          pricingModel: input.pricingModel as string | undefined,
+          pricingRate: input.pricingRate as string | undefined,
+          endpointMcp: input.endpointMcp as string | undefined,
+          endpointA2a: input.endpointA2a as string | undefined,
+          endpointX402: input.endpointX402 as string | undefined,
+          evaluatorDomains: input.evaluatorDomains as string | undefined,
+        });
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "update_profile",
+      description: "Update your agent's Kompass profile. Only provided fields are changed.",
+      schema: z.object({
+        ensNode: z.string().describe("Your ENS namehash (bytes32)"),
+        agentType: z.enum(["provider", "evaluator", "both"]).optional(),
+        categories: z.string().optional(),
+        description: z.string().optional(),
+        paymentMode: z.enum(["escrow", "x402", "hybrid"]).optional(),
+        pricingModel: z.string().optional(),
+        pricingRate: z.string().optional(),
+        endpointMcp: z.string().optional(),
+        endpointA2a: z.string().optional(),
+        endpointX402: z.string().optional(),
+        evaluatorDomains: z.string().optional(),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const { ensNode, ...updates } = input;
+        const result = await kompass.updateProfile(ensNode as `0x${string}`, updates as Record<string, string>);
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "deregister",
+      description: "Remove your agent from the Kompass registry.",
+      schema: z.object({}),
+      func: async () => {
+        const result = await kompass.deregister();
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "approve_usdc",
+      description: "Approve USDC spending for escrow or pipeline. Required before fund_job or create_pipeline.",
+      schema: z.object({
+        spender: z.string().describe("Spender contract address (0x...)"),
+        amount: z.string().describe("Amount in USDC base units. Use 'max' for unlimited."),
+      }),
+      func: async (input: Record<string, unknown>) => {
+        const amount = (input.amount as string) === "max"
+          ? BigInt("0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+          : BigInt(input.amount as string);
+        const result = await kompass.approveToken(input.spender as Address, amount);
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+
+    new DynamicStructuredTool({
+      name: "get_balance",
+      description: "Get this agent's USDC and ETH balance on Base Sepolia.",
+      schema: z.object({}),
+      func: async () => {
+        const result = await kompass.getBalance();
+        return JSON.stringify(result, bigintReplacer);
+      },
+    }),
+  ];
+}

package/src/adapters/openclaw.ts

@@ -0,0 +1,203 @@
+/**
+ * OpenClaw skill adapter for Kompass Protocol.
+ *
+ * Exports a SKILL.md definition and a handler function
+ * for the OpenClaw agent framework.
+ *
+ * @example
+ * ```ts
+ * import { SKILL_MD, handleSkill } from "@kompass/sdk/adapters/openclaw";
+ *
+ * // Register the skill
+ * agent.registerSkill(SKILL_MD, (action, params) => handleSkill(kompass, action, params));
+ * ```
+ */
+import type { Kompass } from "../index.js";
+import type { Address, Hex } from "viem";
+
+const bigintReplacer = (_k: string, v: unknown) => (typeof v === "bigint" ? v.toString() : v);
+
+export const SKILL_MD = `---
+name: kompass
+version: 1.0.0
+description: Discover, hire, and pay AI agents via decentralized escrow on Base
+author: Kompass Protocol
+tags: [defi, agents, escrow, reputation, base]
+---
+
+# Kompass Protocol
+
+Interact with the Kompass agentic commerce protocol on Base.
+Discover agents, create escrow jobs, check reputation, and route DeFi intents.
+
+## Actions
+
+### discover
+Find agents by category and reputation.
+- category (string, optional): Filter category (e.g. "defi", "data")
+- agentType (string, optional): "provider" | "evaluator" | "both"
+- verifiedOnly (boolean, optional): Only return identity-verified agents
+
+### get_agent
+Get a single agent's profile.
+- address (string, required): Agent wallet address
+
+### create_job
+Create an escrow job with a provider and evaluator.
+- provider (string, required): Provider address
+- evaluator (string, required): Evaluator address
+- budget (string, required): Budget in USDC base units
+- expiredAt (string, required): Expiry unix timestamp
+- description (string, required): Job description
+
+### fund_job
+Fund an existing job, locking USDC in escrow.
+- jobId (string, required): Job ID
+
+### submit
+Submit a deliverable for evaluation.
+- jobId (string, required): Job ID
+- deliverable (string, required): Deliverable hash (bytes32)
+
+### complete
+Mark a job as complete, releasing payment (evaluator only).
+- jobId (string, required): Job ID
+- reason (string, optional): Attestation hash
+
+### get_reputation
+Check an agent's onchain ERC-8004 reputation.
+- agentId (string, required): ERC-8004 agent ID
+
+### route_yield_intent
+Route a DeFi yield intent to specialist agents.
+- amount (string, required): Capital in USDC base units
+- riskTolerance (string, required): "conservative" | "balanced" | "aggressive"
+
+### register
+Register your agent on Kompass. Sets ENS text records and calls registerAgent().
+- ensNode (string, required): ENS namehash of your Basename (bytes32)
+- agentType (string, required): "provider" | "evaluator" | "both"
+- categories (string, required): Comma-separated categories
+- description (string, required): What your agent does
+- paymentMode (string, optional): "escrow" | "x402" | "hybrid"
+- pricingRate (string, optional): Price in USDC base units
+
+### update_profile
+Update your agent's profile. Only provided fields are changed.
+- ensNode (string, required): Your ENS namehash
+- categories (string, optional): Updated categories
+- description (string, optional): Updated description
+
+### deregister
+Remove your agent from discovery.
+
+### approve_usdc
+Approve USDC spending for escrow. Required before fund_job.
+- spender (string, required): Spender contract address
+- amount (string, required): Amount in USDC base units
+
+### get_balance
+Get your agent's USDC and ETH balance.
+`;
+
+export async function handleSkill(
+  kompass: Kompass,
+  action: string,
+  params: Record<string, string>
+): Promise<string> {
+  switch (action) {
+    case "discover": {
+      const results = await kompass.discover({
+        category: params.category,
+        agentType: params.agentType as "provider" | "evaluator" | "both" | undefined,
+        verifiedOnly: params.verifiedOnly === "true",
+      });
+      return JSON.stringify(results, bigintReplacer);
+    }
+
+    case "get_agent": {
+      const agent = await kompass.getAgent(params.address);
+      return JSON.stringify(agent, bigintReplacer);
+    }
+
+    case "create_job": {
+      const result = await kompass.createJob({
+        provider: params.provider as Address,
+        evaluator: params.evaluator as Address,
+        budget: BigInt(params.budget),
+        expiredAt: BigInt(params.expiredAt),
+        description: params.description,
+      });
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "fund_job": {
+      const result = await kompass.fund(BigInt(params.jobId));
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "submit": {
+      const result = await kompass.submit(BigInt(params.jobId), params.deliverable as Hex);
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "complete": {
+      const result = await kompass.complete(BigInt(params.jobId), params.reason as Hex | undefined);
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "get_reputation": {
+      const result = await kompass.getReputation(BigInt(params.agentId));
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "route_yield_intent": {
+      const route = await kompass.routeYieldIntent({
+        amount: BigInt(params.amount),
+        riskTolerance: params.riskTolerance as "conservative" | "balanced" | "aggressive",
+        chain: "Base",
+        stablecoin: "USDC",
+      });
+      return JSON.stringify(route, bigintReplacer);
+    }
+
+    case "register": {
+      const result = await kompass.register({
+        ensNode: params.ensNode as `0x${string}`,
+        agentType: params.agentType as "provider" | "evaluator" | "both",
+        categories: params.categories,
+        description: params.description,
+        paymentMode: params.paymentMode as "escrow" | "x402" | "hybrid" | undefined,
+        pricingRate: params.pricingRate,
+      });
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "update_profile": {
+      const { ensNode, ...updates } = params;
+      const result = await kompass.updateProfile(ensNode as `0x${string}`, updates);
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "deregister": {
+      const result = await kompass.deregister();
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "approve_usdc": {
+      const amount = params.amount === "max"
+        ? BigInt("0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff")
+        : BigInt(params.amount);
+      const result = await kompass.approveToken(params.spender as Address, amount);
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    case "get_balance": {
+      const result = await kompass.getBalance();
+      return JSON.stringify(result, bigintReplacer);
+    }
+
+    default:
+      return JSON.stringify({ error: `Unknown action: ${action}` });
+  }
+}