kompass-sdk 0.1.0

package/src/discover.ts

@@ -0,0 +1,187 @@
+import type { KompassConfig, AgentProfile, DiscoverOptions } from "./types.js";
+
+/** Execute a GraphQL query against the Ponder indexer */
+async function queryIndexer<T>(config: KompassConfig, query: string, variables?: Record<string, unknown>): Promise<T> {
+  const response = await fetch(config.indexerUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ query, variables }),
+  });
+
+  if (!response.ok) {
+    throw new Error(`Indexer query failed: ${response.status} ${response.statusText}`);
+  }
+
+  const result = await response.json() as { data?: T; errors?: Array<{ message: string }> };
+
+  if (result.errors?.length) {
+    throw new Error(`Indexer GraphQL error: ${result.errors[0].message}`);
+  }
+
+  if (!result.data) {
+    throw new Error("Indexer returned no data");
+  }
+
+  return result.data;
+}
+
+/** Parse raw agent data from GraphQL into AgentProfile */
+function parseAgent(raw: Record<string, unknown>): AgentProfile {
+  const paymentMode = (raw.paymentMode as AgentProfile["paymentMode"]) ?? "unknown";
+
+  return {
+    id: raw.id as AgentProfile["id"],
+    ensNode: raw.ensNode as `0x${string}`,
+    ensName: (raw.ensName as string) ?? "",
+    agentType: (raw.agentType as AgentProfile["agentType"]) ?? "unknown",
+    categories: (raw.categories as string) ?? "",
+    pricingModel: (raw.pricingModel as string) ?? "",
+    pricingRate: (raw.pricingRate as string) ?? "",
+    pricingToken: (raw.pricingToken as string) ?? "",
+    erc8004Id: (raw.erc8004Id as string) ?? "",
+    identityVerification: (raw.identityVerification as string) ?? "",
+    identityVerified: Boolean(raw.identityVerified),
+    paymentMode,
+    endpointMcp: (raw.endpointMcp as string) ?? "",
+    endpointA2a: (raw.endpointA2a as string) ?? "",
+    endpointX402: (raw.endpointX402 as string) ?? "",
+    x402Enabled: Boolean(raw.x402Enabled),
+    evaluatorDomains: (raw.evaluatorDomains as string) ?? "",
+    description: (raw.description as string) ?? "",
+    registered: raw.registered as boolean,
+    registeredAt: BigInt(raw.registeredAt as string),
+    updatedAt: BigInt(raw.updatedAt as string),
+  };
+}
+
+/**
+ * Discover agents matching criteria via the indexer's GraphQL API.
+ * Filters by category (substring match), agent type, and registration status.
+ */
+export async function discover(config: KompassConfig, options: DiscoverOptions = {}): Promise<AgentProfile[]> {
+  const {
+    category,
+    evaluatorDomain,
+    agentType,
+    paymentMode,
+    requiresX402,
+    verifiedOnly,
+    limit = 50,
+  } = options;
+
+  // Build where clause for Ponder GraphQL
+  const conditions: string[] = ['registered: true'];
+  if (agentType) {
+    conditions.push(`agentType: ${agentType}`);
+  }
+  if (category) {
+    conditions.push(`categories_contains: "${category}"`);
+  }
+  if (evaluatorDomain) {
+    conditions.push(`evaluatorDomains_contains: "${evaluatorDomain}"`);
+  }
+  if (paymentMode) {
+    conditions.push(`paymentMode: "${paymentMode}"`);
+  }
+  if (requiresX402) {
+    conditions.push("x402Enabled: true");
+  }
+  if (verifiedOnly) {
+    conditions.push("identityVerified: true");
+  }
+
+  const where = conditions.length > 0 ? `where: { ${conditions.join(", ")} }` : "";
+
+  const query = `
+    query {
+      agents(${where}, limit: ${limit}) {
+        items {
+          id
+          ensNode
+          ensName
+          agentType
+          categories
+          pricingModel
+          pricingRate
+          pricingToken
+          erc8004Id
+          identityVerification
+          identityVerified
+          paymentMode
+          endpointMcp
+          endpointA2a
+          endpointX402
+          x402Enabled
+          evaluatorDomains
+          description
+          registered
+          registeredAt
+          updatedAt
+        }
+      }
+    }
+  `;
+
+  const data = await queryIndexer<{ agents: { items: Record<string, unknown>[] } }>(config, query);
+  let agents = data.agents.items.map(parseAgent);
+
+  // Client-side filtering for maxPrice (indexer stores as string)
+  if (options.maxPrice !== undefined) {
+    agents = agents.filter((a) => {
+      if (!a.pricingRate) return true;
+      try {
+        return BigInt(a.pricingRate) <= options.maxPrice!;
+      } catch {
+        return true;
+      }
+    });
+  }
+
+  return agents;
+}
+
+/**
+ * Get a single agent's profile by address.
+ */
+export async function getAgent(config: KompassConfig, address: string): Promise<AgentProfile | null> {
+  const query = `
+    query {
+      agent(id: "${address.toLowerCase()}") {
+        id
+        ensNode
+        ensName
+        agentType
+        categories
+        pricingModel
+        pricingRate
+        pricingToken
+        erc8004Id
+        identityVerification
+        identityVerified
+        paymentMode
+        endpointMcp
+        endpointA2a
+        endpointX402
+        x402Enabled
+        evaluatorDomains
+        description
+        registered
+        registeredAt
+        updatedAt
+      }
+    }
+  `;
+
+  const data = await queryIndexer<{ agent: Record<string, unknown> | null }>(config, query);
+  return data.agent ? parseAgent(data.agent) : null;
+}
+
+/**
+ * Find evaluators by domain specialization.
+ */
+export async function findEvaluator(config: KompassConfig, domain: string): Promise<AgentProfile[]> {
+  return discover(config, {
+    category: domain,
+    agentType: "evaluator",
+  });
+}

package/src/escrow.ts

@@ -0,0 +1,284 @@
+import { type Address, type Hex, getContract, parseEventLogs, zeroHash } from "viem";
+import { KompassEscrowAbi } from "./abi.js";
+import type { KompassConfig, CreateJobOptions, CreateJobResult, Job, JobStatus, MilestoneData, MilestoneStatus, TxResult } from "./types.js";
+
+const JOB_STATUS_MAP: Record<number, JobStatus> = {
+  0: "Open",
+  1: "Funded",
+  2: "Submitted",
+  3: "Completed",
+  4: "Rejected",
+  5: "Expired",
+};
+
+const MILESTONE_STATUS_MAP: Record<number, MilestoneStatus> = {
+  0: "Pending",
+  1: "Submitted",
+  2: "Approved",
+  3: "Rejected",
+};
+
+function requireWallet(config: KompassConfig) {
+  if (!config.walletClient) {
+    throw new Error("WalletClient required for write operations");
+  }
+  return config.walletClient;
+}
+
+/**
+ * Create a new job on the escrow contract.
+ * Supports both single-deliverable and multi-milestone jobs.
+ */
+export async function createJob(config: KompassConfig, options: CreateJobOptions): Promise<CreateJobResult> {
+  const wallet = requireWallet(config);
+  const hook = options.hook ?? config.defaultHookAddress ?? ("0x0000000000000000000000000000000000000000" as Address);
+
+  let txHash: Hex;
+
+  if (options.milestones && options.milestones.length > 0) {
+    const shares = options.milestones.map((m) => m.budgetShareBps);
+    txHash = await wallet.writeContract({
+      address: config.escrowAddress,
+      abi: KompassEscrowAbi,
+      functionName: "createJobWithMilestones",
+      args: [
+        options.provider,
+        options.evaluator,
+        options.expiredAt,
+        options.description,
+        hook,
+        shares,
+      ],
+    });
+  } else {
+    txHash = await wallet.writeContract({
+      address: config.escrowAddress,
+      abi: KompassEscrowAbi,
+      functionName: "createJob",
+      args: [
+        options.provider,
+        options.evaluator,
+        options.expiredAt,
+        options.description,
+        hook,
+      ],
+    });
+  }
+
+  // Wait for receipt and extract jobId from JobCreated event
+  const receipt = await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+
+  const logs = parseEventLogs({
+    abi: KompassEscrowAbi,
+    logs: receipt.logs,
+    eventName: "JobCreated",
+  });
+
+  if (logs.length === 0) {
+    throw new Error("JobCreated event not found in transaction receipt");
+  }
+
+  return {
+    txHash,
+    jobId: logs[0].args.jobId,
+  };
+}
+
+/**
+ * Set the budget for an Open job.
+ */
+export async function setBudget(config: KompassConfig, jobId: bigint, amount: bigint): Promise<TxResult> {
+  const wallet = requireWallet(config);
+  const txHash = await wallet.writeContract({
+    address: config.escrowAddress,
+    abi: KompassEscrowAbi,
+    functionName: "setBudget",
+    args: [jobId, amount, "0x"],
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+  return { txHash };
+}
+
+/**
+ * Fund a job, transitioning it from Open to Funded.
+ * Reads the job's budget for the expectedBudget parameter.
+ * Caller must have approved the escrow contract for the budget amount first.
+ */
+export async function fund(config: KompassConfig, jobId: bigint): Promise<TxResult> {
+  const wallet = requireWallet(config);
+
+  // Read current budget for front-running protection
+  const jobData = await config.publicClient.readContract({
+    address: config.escrowAddress,
+    abi: KompassEscrowAbi,
+    functionName: "jobs",
+    args: [jobId],
+  });
+  const budget = jobData[4]; // budget is index 4
+
+  if (budget === 0n) {
+    throw new Error("Job budget is 0 — set budget before funding");
+  }
+
+  const txHash = await wallet.writeContract({
+    address: config.escrowAddress,
+    abi: KompassEscrowAbi,
+    functionName: "fund",
+    args: [jobId, budget, "0x"],
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+  return { txHash };
+}
+
+/**
+ * Submit a deliverable for a job or milestone.
+ * If milestoneIndex is provided, calls submitMilestone; otherwise calls submit.
+ */
+export async function submit(
+  config: KompassConfig,
+  jobId: bigint,
+  deliverable: Hex,
+  milestoneIndex?: number
+): Promise<TxResult> {
+  const wallet = requireWallet(config);
+  let txHash: Hex;
+
+  if (milestoneIndex !== undefined) {
+    txHash = await wallet.writeContract({
+      address: config.escrowAddress,
+      abi: KompassEscrowAbi,
+      functionName: "submitMilestone",
+      args: [jobId, BigInt(milestoneIndex), deliverable],
+    });
+  } else {
+    txHash = await wallet.writeContract({
+      address: config.escrowAddress,
+      abi: KompassEscrowAbi,
+      functionName: "submit",
+      args: [jobId, deliverable, "0x"],
+    });
+  }
+
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+  return { txHash };
+}
+
+/**
+ * Complete a job or milestone (evaluator action).
+ * If milestoneIndex is provided, calls completeMilestone; otherwise calls complete.
+ */
+export async function complete(
+  config: KompassConfig,
+  jobId: bigint,
+  reason?: Hex,
+  milestoneIndex?: number
+): Promise<TxResult> {
+  const wallet = requireWallet(config);
+  const reasonHash = reason ?? zeroHash;
+  let txHash: Hex;
+
+  if (milestoneIndex !== undefined) {
+    txHash = await wallet.writeContract({
+      address: config.escrowAddress,
+      abi: KompassEscrowAbi,
+      functionName: "completeMilestone",
+      args: [jobId, BigInt(milestoneIndex), reasonHash],
+    });
+  } else {
+    txHash = await wallet.writeContract({
+      address: config.escrowAddress,
+      abi: KompassEscrowAbi,
+      functionName: "complete",
+      args: [jobId, reasonHash, "0x"],
+    });
+  }
+
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+  return { txHash };
+}
+
+/**
+ * Complete a job with partial payment (evaluator action).
+ * Releases percentageBps of the budget to the provider, refunds the rest.
+ */
+export async function completePartial(
+  config: KompassConfig,
+  jobId: bigint,
+  percentageBps: number,
+  reason?: Hex
+): Promise<TxResult> {
+  const wallet = requireWallet(config);
+  const reasonHash = reason ?? zeroHash;
+
+  const txHash = await wallet.writeContract({
+    address: config.escrowAddress,
+    abi: KompassEscrowAbi,
+    functionName: "completePartial",
+    args: [jobId, percentageBps, reasonHash],
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+  return { txHash };
+}
+
+/**
+ * Reject a job (client in Open state, evaluator in Funded/Submitted state).
+ */
+export async function reject(config: KompassConfig, jobId: bigint, reason?: Hex): Promise<TxResult> {
+  const wallet = requireWallet(config);
+  const reasonHash = reason ?? zeroHash;
+
+  const txHash = await wallet.writeContract({
+    address: config.escrowAddress,
+    abi: KompassEscrowAbi,
+    functionName: "reject",
+    args: [jobId, reasonHash, "0x"],
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+  return { txHash };
+}
+
+/**
+ * Read a job's full data from the contract.
+ */
+export async function getJob(config: KompassConfig, jobId: bigint): Promise<Job> {
+  const data = await config.publicClient.readContract({
+    address: config.escrowAddress,
+    abi: KompassEscrowAbi,
+    functionName: "jobs",
+    args: [jobId],
+  });
+
+  // Solidity struct auto-getter returns a tuple:
+  // (client, provider, evaluator, hook, budget, expiredAt, status, description, deliverable, milestoneCount, currentMilestone)
+  return {
+    client: data[0] as Address,
+    provider: data[1] as Address,
+    evaluator: data[2] as Address,
+    hook: data[3] as Address,
+    budget: data[4] as bigint,
+    expiredAt: data[5] as bigint,
+    status: JOB_STATUS_MAP[Number(data[6])] ?? "Open",
+    description: data[7] as string,
+    deliverable: data[8] as Hex,
+    milestoneCount: Number(data[9]),
+    currentMilestone: Number(data[10]),
+  };
+}
+
+/**
+ * Read milestones for a job.
+ */
+export async function getMilestones(config: KompassConfig, jobId: bigint): Promise<MilestoneData[]> {
+  const data = await config.publicClient.readContract({
+    address: config.escrowAddress,
+    abi: KompassEscrowAbi,
+    functionName: "getMilestones",
+    args: [jobId],
+  });
+
+  return (data as Array<{ budgetShareBps: number; deliverable: Hex; status: number }>).map((ms) => ({
+    budgetShareBps: Number(ms.budgetShareBps),
+    deliverable: ms.deliverable,
+    status: MILESTONE_STATUS_MAP[Number(ms.status)] ?? "Pending",
+  }));
+}