kompass-sdk 0.1.0

package/src/pipelines.ts

@@ -0,0 +1,253 @@
+import { type Address, type Hex, keccak256, parseEventLogs, toHex } from "viem";
+import type { AgentProfile, KompassConfig, TxResult } from "./types.js";
+import type { IntentRoute, AgentCapabilityRole, YieldIntent } from "./intents.js";
+import { PipelineOrchestratorAbi, Erc20ApproveAbi } from "./pipelineAbi.js";
+
+export type PipelineSettlementMode = "escrow" | "x402";
+
+export interface YieldPipelineSubtask {
+  role: AgentCapabilityRole;
+  provider: Address;
+  evaluator: Address;
+  budget: bigint;
+  description: string;
+  dependencies: number[];
+  settlementMode: PipelineSettlementMode;
+  agent: AgentProfile;
+}
+
+export interface YieldPipelinePlan {
+  token: Address;
+  intentHash: Hex;
+  intentSummary: string;
+  subtasks: YieldPipelineSubtask[];
+  offchainSteps: Array<{
+    role: AgentCapabilityRole;
+    description: string;
+    endpointX402: string;
+    agent: AgentProfile;
+  }>;
+}
+
+export interface CreatePipelineOptions {
+  token?: Address;
+  autoApprove?: boolean;
+  autoActivate?: boolean;
+}
+
+export interface CreatePipelineResult extends TxResult {
+  pipelineId: bigint;
+  approveTxHash?: Hex;
+  fundTxHash: Hex;
+  activateTxHash?: Hex;
+}
+
+function requireWallet(config: KompassConfig) {
+  if (!config.walletClient) {
+    throw new Error("WalletClient required for pipeline creation");
+  }
+  return config.walletClient;
+}
+
+function requirePipelineAddress(config: KompassConfig): Address {
+  if (!config.pipelineAddress) {
+    throw new Error("pipelineAddress is required in KompassConfig for pipeline operations");
+  }
+  return config.pipelineAddress;
+}
+
+function roleLabel(role: AgentCapabilityRole): string {
+  switch (role) {
+    case "research":
+      return "research";
+    case "premium-data":
+      return "premium data";
+    case "risk":
+      return "risk review";
+    case "execution":
+      return "execution";
+  }
+}
+
+function inferSettlementMode(agent: AgentProfile, role: AgentCapabilityRole): PipelineSettlementMode {
+  if (role === "premium-data") return "x402";
+  if (agent.paymentMode === "x402" && !agent.endpointX402) return "x402";
+  return "escrow";
+}
+
+function fallbackBudget(agent: AgentProfile, role: AgentCapabilityRole, intent: YieldIntent): bigint {
+  const basisPoints =
+    role === "premium-data" ? 50n :
+    role === "research" ? 125n :
+    role === "risk" ? 100n :
+    150n;
+  return (intent.amount * basisPoints) / 10_000n;
+}
+
+export function buildYieldPipelinePlan(route: IntentRoute, options: { token: Address }): YieldPipelinePlan {
+  const riskAgent = route.steps.find((step) => step.role === "risk")?.agent;
+  const onchainSubtasks: YieldPipelineSubtask[] = [];
+  const offchainSteps: YieldPipelinePlan["offchainSteps"] = [];
+  const stepIndexByRole = new Map<AgentCapabilityRole, number>();
+
+  for (const step of route.steps) {
+    if (!step.agent) continue;
+
+    const settlementMode = inferSettlementMode(step.agent, step.role);
+    const budget = step.agent.pricingRate
+      ? BigInt(step.agent.pricingRate)
+      : fallbackBudget(step.agent, step.role, route.intent);
+
+    if (settlementMode === "x402") {
+      offchainSteps.push({
+        role: step.role,
+        description: `Use ${step.agent.ensName || step.agent.id} for ${roleLabel(step.role)} over x402 before escrow execution.`,
+        endpointX402: step.agent.endpointX402,
+        agent: step.agent,
+      });
+      continue;
+    }
+
+    const dependencies: number[] = [];
+    const previousResearch = stepIndexByRole.get("research");
+    const previousRisk = stepIndexByRole.get("risk");
+
+    if (step.role === "risk" && previousResearch !== undefined) {
+      dependencies.push(previousResearch);
+    }
+
+    if (step.role === "execution") {
+      if (previousRisk !== undefined) {
+        dependencies.push(previousRisk);
+      } else if (previousResearch !== undefined) {
+        dependencies.push(previousResearch);
+      }
+    }
+
+    const evaluator = riskAgent?.id ?? step.agent.id;
+
+    onchainSubtasks.push({
+      role: step.role,
+      provider: step.agent.id,
+      evaluator,
+      budget,
+      description: `${step.title}: ${step.summary}`,
+      dependencies,
+      settlementMode,
+      agent: step.agent,
+    });
+    stepIndexByRole.set(step.role, onchainSubtasks.length - 1);
+  }
+
+  return {
+    token: options.token,
+    intentHash: keccak256(toHex(route.summary)),
+    intentSummary: route.summary,
+    subtasks: onchainSubtasks,
+    offchainSteps,
+  };
+}
+
+export async function createYieldPipeline(
+  config: KompassConfig,
+  route: IntentRoute,
+  options: CreatePipelineOptions = {}
+): Promise<CreatePipelineResult> {
+  const wallet = requireWallet(config);
+  const pipelineAddress = requirePipelineAddress(config);
+  const token = options.token ?? config.paymentTokenAddress;
+
+  if (!token) {
+    throw new Error("paymentTokenAddress is required in KompassConfig or createYieldPipeline options");
+  }
+
+  const plan = buildYieldPipelinePlan(route, { token });
+  if (plan.subtasks.length === 0) {
+    throw new Error("No escrow-capable subtasks were generated for this intent route");
+  }
+
+  const hookAddress = config.defaultHookAddress;
+  const createTxHash = hookAddress
+    ? await wallet.writeContract({
+        address: pipelineAddress,
+        abi: PipelineOrchestratorAbi,
+        functionName: "createPipelineWithHook",
+        args: [token, plan.intentHash, hookAddress],
+      })
+    : await wallet.writeContract({
+        address: pipelineAddress,
+        abi: PipelineOrchestratorAbi,
+        functionName: "createPipeline",
+        args: [token, plan.intentHash],
+      });
+
+  const createReceipt = await config.publicClient.waitForTransactionReceipt({ hash: createTxHash });
+  const events = parseEventLogs({
+    abi: PipelineOrchestratorAbi,
+    logs: createReceipt.logs,
+    eventName: "PipelineCreated",
+  });
+
+  if (events.length === 0) {
+    throw new Error("PipelineCreated event not found in receipt");
+  }
+
+  const pipelineId = events[0].args.pipelineId;
+
+  for (const subtask of plan.subtasks) {
+    const descriptionHash = keccak256(toHex(subtask.description));
+    const addTxHash = await wallet.writeContract({
+      address: pipelineAddress,
+      abi: PipelineOrchestratorAbi,
+      functionName: "addSubTask",
+      args: [
+        pipelineId,
+        subtask.provider,
+        subtask.evaluator,
+        subtask.budget,
+        descriptionHash,
+        subtask.dependencies.map((dependency) => BigInt(dependency)),
+      ],
+    });
+    await config.publicClient.waitForTransactionReceipt({ hash: addTxHash });
+  }
+
+  let approveTxHash: Hex | undefined;
+  const totalBudget = plan.subtasks.reduce((sum, subtask) => sum + subtask.budget, 0n);
+  if (options.autoApprove ?? true) {
+    approveTxHash = await wallet.writeContract({
+      address: token,
+      abi: Erc20ApproveAbi,
+      functionName: "approve",
+      args: [pipelineAddress, totalBudget],
+    });
+    await config.publicClient.waitForTransactionReceipt({ hash: approveTxHash });
+  }
+
+  const fundTxHash = await wallet.writeContract({
+    address: pipelineAddress,
+    abi: PipelineOrchestratorAbi,
+    functionName: "fundPipeline",
+    args: [pipelineId],
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: fundTxHash });
+
+  let activateTxHash: Hex | undefined;
+  if (options.autoActivate ?? true) {
+    activateTxHash = await wallet.writeContract({
+      address: pipelineAddress,
+      abi: PipelineOrchestratorAbi,
+      functionName: "activateNextTasks",
+      args: [pipelineId],
+    });
+    await config.publicClient.waitForTransactionReceipt({ hash: activateTxHash });
+  }
+
+  return {
+    txHash: createTxHash,
+    pipelineId,
+    approveTxHash,
+    fundTxHash,
+    activateTxHash,
+  };
+}

package/src/registry.ts

@@ -0,0 +1,232 @@
+import { encodePacked, type Hex } from "viem";
+import { KompassRegistryAbi } from "./abi.js";
+import type { KompassConfig, RegisterProfile, TxResult } from "./types.js";
+
+/** ENS text record key mapping */
+const RECORD_KEYS: Record<string, string> = {
+  ensName: "com.kompass.identity.name",
+  agentType: "com.kompass.type",
+  categories: "com.kompass.categories",
+  erc8004Id: "com.kompass.erc8004.id",
+  identityVerification: "com.kompass.identity.verification",
+  paymentMode: "com.kompass.payment.mode",
+  pricingModel: "com.kompass.pricing.model",
+  pricingRate: "com.kompass.pricing.rate",
+  pricingToken: "com.kompass.pricing.token",
+  endpointMcp: "com.kompass.endpoint.mcp",
+  endpointA2a: "com.kompass.endpoint.a2a",
+  endpointX402: "com.kompass.endpoint.x402",
+  evaluatorDomains: "com.kompass.evaluator.domains",
+  description: "com.kompass.description",
+};
+
+/** ENS L2 Resolver ABI (just setText) */
+const resolverAbi = [
+  {
+    type: "function",
+    name: "setText",
+    inputs: [
+      { name: "node", type: "bytes32" },
+      { name: "key", type: "string" },
+      { name: "value", type: "string" },
+    ],
+    outputs: [],
+    stateMutability: "nonpayable",
+  },
+] as const;
+
+function requireWallet(config: KompassConfig) {
+  if (!config.walletClient) {
+    throw new Error("WalletClient required for write operations");
+  }
+  return config.walletClient;
+}
+
+// ── ENSIP-25 Helpers ────────────────────────────────────
+
+/**
+ * Compute the ENSIP-25 text record key for an agent.
+ *
+ * Format: `agent-registration[<registryIdentifier>][<agentId>]`
+ * Where registryIdentifier = encodePacked(chainId, registryType, registryAddress)
+ *
+ * @see https://docs.ens.domains/ensip/25
+ */
+export function computeENSIP25Key(
+  chainId: bigint,
+  registryAddress: `0x${string}`,
+  agentId: string,
+  registryType: number = 0x01 // ERC-8004
+): string {
+  const registryIdentifier = encodePacked(
+    ["uint256", "uint8", "address"],
+    [chainId, registryType, registryAddress as `0x${string}`]
+  );
+  return `agent-registration[${registryIdentifier}][${agentId}]`;
+}
+
+/**
+ * Set the ENSIP-25 text record on an agent's ENS name.
+ * Creates bidirectional verification: ENS name → on-chain agent identity.
+ */
+export async function setENSIP25Record(
+  config: KompassConfig,
+  ensNode: Hex,
+  agentId: string,
+  chainId: bigint = 84532n // Base Sepolia
+): Promise<TxResult> {
+  const wallet = requireWallet(config);
+
+  const resolverAddress = await config.publicClient.readContract({
+    address: config.registryAddress,
+    abi: KompassRegistryAbi,
+    functionName: "resolver",
+  });
+
+  const key = computeENSIP25Key(
+    chainId,
+    config.reputationRegistryAddress,
+    agentId
+  );
+
+  const txHash = await wallet.writeContract({
+    address: resolverAddress,
+    abi: resolverAbi,
+    functionName: "setText",
+    args: [ensNode, key, "1"],
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+
+  return { txHash };
+}
+
+/**
+ * Register an agent with the Kompass protocol.
+ *
+ * Flow:
+ * 1. Set ENS text records on the L2 resolver (from the agent's wallet)
+ * 2. Call registerAgent(ensNode) on the registry contract
+ *
+ * The caller must own the Basename identified by ensNode.
+ */
+export async function register(config: KompassConfig, profile: RegisterProfile): Promise<TxResult> {
+  const wallet = requireWallet(config);
+
+  // Step 1: Read the resolver address from the registry contract
+  const resolverAddress = await config.publicClient.readContract({
+    address: config.registryAddress,
+    abi: KompassRegistryAbi,
+    functionName: "resolver",
+  });
+
+  // Step 2: Set ENS text records on the resolver
+  for (const [field, key] of Object.entries(RECORD_KEYS)) {
+    const value = profile[field as keyof RegisterProfile];
+    if (value !== undefined && typeof value === "string" && value !== "") {
+      const setTxHash = await wallet.writeContract({
+        address: resolverAddress,
+        abi: resolverAbi,
+        functionName: "setText",
+        args: [profile.ensNode, key, value],
+      });
+      await config.publicClient.waitForTransactionReceipt({ hash: setTxHash });
+    }
+  }
+
+  if (profile.identityVerification) {
+    const verificationTxHash = await wallet.writeContract({
+      address: resolverAddress,
+      abi: resolverAbi,
+      functionName: "setText",
+      args: [profile.ensNode, profile.identityVerification, "verified"],
+    });
+    await config.publicClient.waitForTransactionReceipt({ hash: verificationTxHash });
+  }
+
+  // Step 3: Register the agent on the registry contract
+  const txHash = await wallet.writeContract({
+    address: config.registryAddress,
+    abi: KompassRegistryAbi,
+    functionName: "registerAgent",
+    args: [profile.ensNode],
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+
+  // Step 4: Set ENSIP-25 text record for bidirectional agent verification
+  // Uses the ERC-8004 agent ID from the profile if available
+  if (profile.erc8004Id) {
+    try {
+      await setENSIP25Record(config, profile.ensNode, profile.erc8004Id);
+    } catch (err) {
+      // Non-critical: registration succeeded, ENSIP-25 is bonus
+      console.warn("ENSIP-25 text record failed (non-critical):", err);
+    }
+  }
+
+  return { txHash };
+}
+
+/**
+ * Update an agent's ENS text records.
+ * Only updates the fields that are provided (non-undefined).
+ */
+export async function updateProfile(
+  config: KompassConfig,
+  ensNode: Hex,
+  updates: Partial<Omit<RegisterProfile, "ensNode">>
+): Promise<TxResult> {
+  const wallet = requireWallet(config);
+
+  const resolverAddress = await config.publicClient.readContract({
+    address: config.registryAddress,
+    abi: KompassRegistryAbi,
+    functionName: "resolver",
+  });
+
+  let lastTxHash: Hex = "0x" as Hex;
+
+  for (const [field, key] of Object.entries(RECORD_KEYS)) {
+    const value = updates[field as keyof typeof updates];
+    if (value !== undefined && typeof value === "string") {
+      lastTxHash = await wallet.writeContract({
+        address: resolverAddress,
+        abi: resolverAbi,
+        functionName: "setText",
+        args: [ensNode, key, value],
+      });
+      await config.publicClient.waitForTransactionReceipt({ hash: lastTxHash });
+    }
+  }
+
+  if (typeof updates.identityVerification === "string" && updates.identityVerification !== "") {
+    lastTxHash = await wallet.writeContract({
+      address: resolverAddress,
+      abi: resolverAbi,
+      functionName: "setText",
+      args: [ensNode, updates.identityVerification, "verified"],
+    });
+    await config.publicClient.waitForTransactionReceipt({ hash: lastTxHash });
+  }
+
+  if (lastTxHash === "0x") {
+    throw new Error("No fields provided to update");
+  }
+
+  return { txHash: lastTxHash };
+}
+
+/**
+ * Deregister an agent from the protocol.
+ */
+export async function deregister(config: KompassConfig): Promise<TxResult> {
+  const wallet = requireWallet(config);
+
+  const txHash = await wallet.writeContract({
+    address: config.registryAddress,
+    abi: KompassRegistryAbi,
+    functionName: "deregister",
+  });
+  await config.publicClient.waitForTransactionReceipt({ hash: txHash });
+
+  return { txHash };
+}

package/src/reputation.ts

@@ -0,0 +1,43 @@
+import type { Address } from "viem";
+import { ERC8004ReputationAbi } from "./abi.js";
+import type { KompassConfig, ReputationSummary } from "./types.js";
+
+/**
+ * Get reputation summary for an agent from the ERC-8004 Reputation Registry.
+ *
+ * @param agentId - The ERC-8004 agent ID (uint256)
+ * @param tag1 - Optional primary tag filter (e.g., "job-completed")
+ * @param tag2 - Optional secondary tag filter
+ */
+export async function getReputation(
+  config: KompassConfig,
+  agentId: bigint,
+  tag1: string = "",
+  tag2: string = ""
+): Promise<ReputationSummary> {
+  // First get all clients who have given feedback
+  const clients = await config.publicClient.readContract({
+    address: config.reputationRegistryAddress,
+    abi: ERC8004ReputationAbi,
+    functionName: "getClients",
+    args: [agentId],
+  });
+
+  if ((clients as Address[]).length === 0) {
+    return { count: 0n, summaryValue: 0n, summaryValueDecimals: 0 };
+  }
+
+  // Get summary across all clients
+  const [count, summaryValue, summaryValueDecimals] = await config.publicClient.readContract({
+    address: config.reputationRegistryAddress,
+    abi: ERC8004ReputationAbi,
+    functionName: "getSummary",
+    args: [agentId, clients as Address[], tag1, tag2],
+  });
+
+  return {
+    count: BigInt(count),
+    summaryValue: BigInt(summaryValue),
+    summaryValueDecimals: Number(summaryValueDecimals),
+  };
+}