@blindmarket/sdk 0.1.6 → 0.1.8

package/src/chain/domain-types.ts

@@ -0,0 +1,92 @@
+import type { Address, Hex, TaskId, TaskStatus } from '../types.js';
+
+// ── Chain-agnostic domain types ───────────────────────────────────────────
+// These types are the BlindMarket domain model, independent of any specific
+// blockchain. Each chain adapter translates between these and its native
+// contract types.
+
+export type BlockchainType = 'evm';
+
+/** Base fields shared by all chain network configs. */
+export interface NetworkBase {
+  name: string;
+  chainType: BlockchainType;
+  rpc: string[];
+  explorer?: string;
+}
+
+/** EVM-compatible chain network config (0G, Ethereum, Polygon, etc.). */
+export interface EVMNetwork extends NetworkBase {
+  chainType: 'evm';
+  chainId: number;
+  contracts: {
+    escrow: Address;
+    registry: Address;
+    reputation: Address;
+    usdc: Address;
+  };
+  indexer?: string;
+  broker?: string;
+}
+
+/** Union of all supported chain network configs. */
+export type Network = EVMNetwork;
+
+/** Parameters for creating a task on any chain. */
+export interface CreateTaskParams {
+  taskHash: Hex;
+  token: Address | string;
+  amount: bigint;
+  category: string;
+  locationZone: string;
+  deadline: bigint;
+  /** Per-task verifier address (agent-verification mode). Optional. */
+  verifierAgent?: string;
+}
+
+/** Decoded on-chain task representation (chain-agnostic). */
+export interface DomainTask {
+  taskId: TaskId;
+  agent: string;
+  worker: string;
+  token: string;
+  amount: bigint;
+  taskHash: Hex;
+  evidenceHash: Hex;
+  status: TaskStatus;
+  category: string;
+  locationZone: string;
+  createdAt: Date;
+  deadline: Date;
+}
+
+/** Task metadata used for discovery / listing. */
+export interface DomainTaskMeta {
+  taskId: TaskId;
+  agent: string;
+  category: string;
+  locationZone: string;
+  reward: bigint;
+  createdAt: Date;
+  isOpen: boolean;
+}
+
+/** On-chain reputation snapshot (chain-agnostic). */
+export interface DomainReputation {
+  tasksCompleted: bigint;
+  totalScore: bigint;
+  disputes: bigint;
+  avgScore: number;
+}
+
+/** Transaction receipt (chain-agnostic). */
+export interface DomainTxReceipt {
+  hash: string;
+  blockNumber?: number;
+}
+
+/** Signer abstraction that works across chains. */
+export interface ChainSigner {
+  getAddress(): Promise<string>;
+  getChainType(): BlockchainType;
+}

package/src/chain/evm/EVMChainAdapter.ts

@@ -0,0 +1,212 @@
+import { ethers } from 'ethers';
+import type { Address, Hex } from '../../types.js';
+import { ChainClient, type ChainClientOptions } from '../ChainClient.js';
+import { resolveNetwork } from '../../network/resolve.js';
+import type { EthersSigner } from '../../signer/EthersSigner.js';
+import type { Signer } from '../../signer/Signer.js';
+import type {
+  CreateTaskParams,
+  DomainReputation,
+  DomainTask,
+  DomainTaskMeta,
+  DomainTxReceipt,
+  EVMNetwork,
+} from '../domain-types.js';
+import type { IBlindMarketChain } from '../IBlindMarketChain.js';
+import type { OpenTaskMeta } from '../TaskRegistryClient.js';
+
+/**
+ * EVM-compatible implementation of IBlindMarketChain.
+ *
+ * Wraps the existing ChainClient (which bundles BlindEscrowClient,
+ * TaskRegistryClient, and BlindReputationClient) and translates domain
+ * operations into ethers v6 contract calls on EVM chains (0G, Ethereum, etc.).
+ */
+export class EVMChainAdapter implements IBlindMarketChain {
+  readonly network: EVMNetwork;
+  private client: ChainClient;
+  private signer: EthersSigner | undefined;
+
+  constructor(opts: ChainClientOptions) {
+    const resolved = resolveNetwork(opts.network);
+    if (resolved.chainType !== 'evm') {
+      throw new Error(`EVMChainAdapter requires an EVM network, got ${resolved.chainType}`);
+    }
+    this.network = resolved;
+    this.client = new ChainClient(opts);
+    this.signer = opts.signer as EthersSigner | undefined;
+  }
+
+  async getAddress(): Promise<string> {
+    if (!this.signer) throw new Error('No signer configured');
+    return this.signer.getAddress();
+  }
+
+  // ── Task lifecycle ──────────────────────────────────────────────────────
+
+  async createTask(params: CreateTaskParams): Promise<{ taskId: bigint; receipt: DomainTxReceipt }> {
+    const result = await this.client.escrow.createTask({
+      taskHash: params.taskHash,
+      token: params.token as Address,
+      amount: params.amount,
+      category: params.category,
+      locationZone: params.locationZone,
+      deadline: params.deadline,
+    });
+    return {
+      taskId: result.taskId,
+      receipt: {
+        hash: result.receipt.hash,
+        blockNumber: result.receipt.blockNumber,
+      },
+    };
+  }
+
+  async assignWorker(taskId: bigint, worker: string): Promise<DomainTxReceipt> {
+    const receipt = await this.client.escrow.assignWorker(taskId, worker as Address);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async submitEvidence(taskId: bigint, evidenceHash: string): Promise<DomainTxReceipt> {
+    const receipt = await this.client.escrow.submitEvidence(taskId, evidenceHash as Hex);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async completeVerification(taskId: bigint, passed: boolean): Promise<DomainTxReceipt> {
+    const receipt = await this.client.escrow.completeVerification(taskId, passed);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async cancelTask(taskId: bigint): Promise<DomainTxReceipt> {
+    const receipt = await this.client.escrow.cancelTask(taskId);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async claimTimeout(taskId: bigint): Promise<DomainTxReceipt> {
+    const receipt = await this.client.escrow.claimTimeout(taskId);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async raiseDispute(taskId: bigint): Promise<DomainTxReceipt> {
+    const receipt = await this.client.escrow.raiseDispute(taskId);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async resolveDispute(taskId: bigint, workerFavored: boolean): Promise<DomainTxReceipt> {
+    const receipt = await this.client.escrow.resolveDispute(taskId, workerFavored);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async getTask(taskId: bigint): Promise<DomainTask> {
+    const onChain = await this.client.escrow.getTask(taskId);
+    return {
+      ...onChain,
+      category: '',        // OnChainTask doesn't decode these contract fields;
+      locationZone: '',    // they are present in the Solidity Task struct.
+    };
+  }
+
+  async isTaskExpired(taskId: bigint): Promise<boolean> {
+    return this.client.escrow.isTaskExpired(taskId);
+  }
+
+  // ── Task discovery ──────────────────────────────────────────────────────
+
+  async publishTask(taskId: bigint, _meta: Omit<DomainTaskMeta, 'taskId'> & { taskId?: bigint }): Promise<DomainTxReceipt> {
+    // The EVM contracts publish tasks via the escrow's TaskCreated event
+    // (handled by the backend indexer). This is a no-op at the adapter level
+    // for EVM — the registry is updated by the escrow contract internally.
+    // Return a stub receipt for interface compatibility.
+    return { hash: '0x0', blockNumber: 0 };
+  }
+
+  async closeTask(taskId: bigint): Promise<DomainTxReceipt> {
+    const receipt = await this.client.registry.closeTask(taskId);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async getOpenTasks(offset: bigint, limit: bigint): Promise<DomainTaskMeta[]> {
+    const taskIds = await this.client.registry.getOpenTasks(offset, limit);
+    const metas = await Promise.all(
+      taskIds.map(async (tid: bigint) => {
+        const meta = await this.client.registry.getTaskMeta(tid);
+        return {
+          taskId: tid,
+          agent: '' as Address, // EVM TaskRegistry stores agent; use meta directly
+          category: meta.category,
+          locationZone: meta.locationZone,
+          reward: meta.reward,
+          createdAt: meta.createdAt,
+          isOpen: true,
+        } as DomainTaskMeta;
+      }),
+    );
+    return metas;
+  }
+
+  async openTaskCount(): Promise<bigint> {
+    return this.client.registry.openTaskCount();
+  }
+
+  async totalTasks(): Promise<bigint> {
+    return this.client.registry.totalTasks();
+  }
+
+  // ── Reputation ──────────────────────────────────────────────────────────
+
+  async rateWorker(worker: string, score: number, taskId: bigint): Promise<DomainTxReceipt> {
+    const receipt = await this.client.reputation.rate(worker as Address, score, taskId);
+    return { hash: receipt.hash, blockNumber: receipt.blockNumber };
+  }
+
+  async recordDispute(worker: string, taskId: bigint): Promise<DomainTxReceipt> {
+    // EVM BlindReputation doesn't expose recordDispute as a standalone client
+    // method in the SDK — the escrow calls it internally. For external callers
+    // we throw. The escrow contract handles dispute recording via its own path.
+    throw new Error('recordDispute is handled internally by BlindEscrow on EVM chains');
+  }
+
+  async getReputation(worker: string): Promise<DomainReputation> {
+    return this.client.reputation.getReputation(worker as Address);
+  }
+
+  async hasBeenRated(worker: string, taskId: bigint): Promise<boolean> {
+    return this.client.reputation.hasBeenRated(worker as Address, taskId);
+  }
+
+  // ── Agent identity ──────────────────────────────────────────────────────
+
+  async mintAgent(params: {
+    to: string;
+    encryptedURI: string;
+    metadataHash: string;
+  }): Promise<{ tokenId: bigint; receipt: DomainTxReceipt }> {
+    // INFT minting is handled by the backend (services/chain.ts → inft.mint()).
+    // The SDK doesn't expose a direct INFT client. For direct EVM calls,
+    // consumers can use the raw ethers.Contract via the unwrapped signer.
+    throw new Error('INFT minting is backend-managed on EVM chains. Use the REST API or raw ethers.Contract.');
+  }
+
+  async getEncryptedURI(_tokenId: bigint): Promise<string> {
+    throw new Error('INFT URI reading is backend-managed on EVM chains. Use the REST API or raw ethers.Contract.');
+  }
+
+  // ── Queries ─────────────────────────────────────────────────────────────
+
+  async getBalance(address: string): Promise<bigint> {
+    return this.client.provider.getBalance(address);
+  }
+
+  // ── Accessors for direct ethers access (advanced use) ───────────────────
+
+  /** Get the underlying ethers Provider for raw queries. */
+  getProvider(): ethers.Provider {
+    return this.client.provider;
+  }
+
+  /** Get the underlying ethers Signer (if configured). */
+  getEthersSigner(): ethers.Signer | undefined {
+    if (!this.signer) return undefined;
+    return (this.signer as unknown as { inner?: ethers.Signer }).inner;
+  }
+}

package/src/chain/evm/index.ts

@@ -0,0 +1 @@
+export { EVMChainAdapter } from './EVMChainAdapter.js';

package/src/chain/index.ts

@@ -4,3 +4,9 @@ export * from './BlindEscrowClient.js';
 export * from './TaskRegistryClient.js';
 export * from './BlindReputationClient.js';
 export * from './ChainClient.js';
+
+// Chain-agnostic domain interface (EVM only — 0G Chain)
+export * from './IBlindMarketChain.js';
+export * from './domain-types.js';
+export * from './createChainAdapter.js';
+export * from './evm/index.js';

package/src/executor/WorkerRuntime.ts

@@ -0,0 +1,338 @@
+import { BlindMarket } from '../index.js';
+import { eciesDecrypt, aesDecrypt } from '../crypto/index.js';
+import type {
+  A2ATaskState, AgentCapability, ExecutorProfile, Message,
+} from '../types.js';
+
+// ── Config ──────────────────────────────────────────────────────────────────
+
+export interface WorkerRuntimeConfig {
+  apiKey: string;
+  apiBase?: string;
+  displayName: string;
+  capabilities: AgentCapability[];
+  executeTask: ExecuteTaskHandler;
+  existingPrivateKey?: string;
+  existingAddress?: string;
+  existingPublicKey?: string;
+  minReward?: string;
+  preferredCapabilities?: AgentCapability[];
+  browseIntervalMs?: number;
+  watchIntervalMs?: number;
+  maxConcurrentTasks?: number;
+}
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export type ExecuteTaskHandler = (ctx: TaskContext) => Promise<Record<string, unknown>>;
+
+export interface TaskContext {
+  taskId: string;
+  task: A2ATaskState;
+  instructions: string;
+}
+
+export interface TaskExecutionInfo {
+  taskId: string;
+  status: 'bidding' | 'assigned' | 'working' | 'submitted' | 'completed' | 'failed';
+  task?: A2ATaskState;
+  error?: string;
+  startedAt: number;
+}
+
+export type WorkerRuntimeEvent =
+  | { type: 'started' }
+  | { type: 'stopped' }
+  | { type: 'paused' }
+  | { type: 'resumed' }
+  | { type: 'registered'; profile: ExecutorProfile }
+  | { type: 'task_found'; taskId: string; task: A2ATaskState }
+  | { type: 'task_bidded'; taskId: string }
+  | { type: 'task_assigned'; taskId: string }
+  | { type: 'task_accepted'; taskId: string }
+  | { type: 'task_working'; taskId: string }
+  | { type: 'task_executed'; taskId: string }
+  | { type: 'task_submitted'; taskId: string; result: Record<string, unknown> }
+  | { type: 'task_failed'; taskId: string; error: string }
+  | { type: 'message_received'; message: Message; count: number }
+  | { type: 'browse_done'; found: number }
+  | { type: 'error'; error: string };
+
+// ── Defaults ────────────────────────────────────────────────────────────────
+
+const DEFAULTS = {
+  browseIntervalMs: 15_000,
+  watchIntervalMs: 5_000,
+  maxConcurrentTasks: 3,
+};
+
+// ── WorkerRuntime ───────────────────────────────────────────────────────────
+
+export class WorkerRuntime {
+  private bb: BlindMarket;
+  private config: WorkerRuntimeConfig & typeof DEFAULTS;
+  private wallet?: { address: string; privateKey: string; publicKey: string };
+  private profile?: ExecutorProfile;
+  private running = false;
+  private paused = false;
+  private browseTimer?: ReturnType<typeof setInterval>;
+  private watchTimers = new Map<string, ReturnType<typeof setInterval>>();
+  private executions = new Map<string, TaskExecutionInfo>();
+  private listeners = new Set<(event: WorkerRuntimeEvent) => void>();
+
+  constructor(config: WorkerRuntimeConfig) {
+    this.config = { ...DEFAULTS, ...config };
+    this.bb = new BlindMarket({ apiKey: config.apiKey, apiBase: config.apiBase });
+  }
+
+  // ── Status ──────────────────────────────────────────────────────────────
+
+  get isRunning(): boolean {
+    return this.running;
+  }
+
+  get isPaused(): boolean {
+    return this.paused;
+  }
+
+  get activeExecutions(): TaskExecutionInfo[] {
+    return [...this.executions.values()];
+  }
+
+  /** Get own executor profile (available after start). */
+  get executorProfile(): ExecutorProfile | undefined {
+    return this.profile;
+  }
+
+  /** Get own wallet info (available after start). */
+  get executorWallet(): { address: string; publicKey: string } | undefined {
+    return this.wallet;
+  }
+
+  // ── Events ──────────────────────────────────────────────────────────────
+
+  on(listener: (event: WorkerRuntimeEvent) => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  private emit(event: WorkerRuntimeEvent): void {
+    for (const l of this.listeners) l(event);
+  }
+
+  // ── Lifecycle ───────────────────────────────────────────────────────────
+
+  async start(): Promise<ExecutorProfile> {
+    if (this.running) return this.profile!;
+
+    // 1. Register or restore executor
+    if (this.config.existingPrivateKey && this.config.existingAddress && this.config.existingPublicKey) {
+      this.wallet = {
+        address: this.config.existingAddress,
+        privateKey: this.config.existingPrivateKey,
+        publicKey: this.config.existingPublicKey,
+      };
+      // Fetch existing profile — backend identifies by API key
+      const result = await this.bb.getExecutorProfile();
+      this.profile = result.agent;
+    } else {
+      const result = await this.bb.createAgent({
+        displayName: this.config.displayName,
+        capabilities: this.config.capabilities,
+        minReward: this.config.minReward,
+        preferredCapabilities: this.config.preferredCapabilities,
+      });
+      this.wallet = {
+        address: result.wallet.address,
+        privateKey: result.wallet.privateKey,
+        publicKey: result.wallet.publicKey,
+      };
+      this.profile = result.executor;
+    }
+
+    this.emit({ type: 'registered', profile: this.profile });
+
+    // 2. Start the browse loop
+    this.running = true;
+    this.startBrowseLoop();
+    this.emit({ type: 'started' });
+
+    return this.profile;
+  }
+
+  stop(): void {
+    this.running = false;
+    if (this.browseTimer) {
+      clearInterval(this.browseTimer);
+      this.browseTimer = undefined;
+    }
+    for (const t of this.watchTimers.values()) clearInterval(t);
+    this.watchTimers.clear();
+    this.emit({ type: 'stopped' });
+  }
+
+  pause(): void {
+    if (!this.running || this.paused) return;
+    this.paused = true;
+    this.emit({ type: 'paused' });
+  }
+
+  resume(): void {
+    if (!this.running || !this.paused) return;
+    this.paused = false;
+    this.emit({ type: 'resumed' });
+    // Immediately browse instead of waiting for next interval
+    this.browse();
+  }
+
+  // ── Browse loop ─────────────────────────────────────────────────────────
+
+  private startBrowseLoop(): void {
+    const ms = this.config.browseIntervalMs;
+    this.browseTimer = setInterval(() => this.browse(), ms);
+    this.browse();
+  }
+
+  private async browse(): Promise<void> {
+    if (this.paused) return;
+    try {
+      const active = this.activeExecutions;
+      const inFlight = active.filter(e => e.status === 'bidding' || e.status === 'working').length;
+      if (inFlight >= this.config.maxConcurrentTasks) return;
+
+      const result = await this.bb.browseA2ATasks({
+        capabilities: this.config.capabilities,
+      });
+
+      this.emit({ type: 'browse_done', found: result.tasks.length });
+
+      for (const task of result.tasks) {
+        if (this.executions.has(task.taskId)) continue;
+        if (task.status !== 'open' && task.status !== 'bidding') continue;
+        if (task.executorAddress && task.executorAddress !== this.wallet?.address) continue;
+
+        this.executions.set(task.taskId, {
+          taskId: task.taskId,
+          status: 'bidding',
+          task,
+          startedAt: Date.now(),
+        });
+
+        this.emit({ type: 'task_found', taskId: task.taskId, task });
+
+        await this.bb.bidOnTask(task.taskId);
+        this.emit({ type: 'task_bidded', taskId: task.taskId });
+
+        this.watchForAssignment(task.taskId);
+      }
+    } catch (err) {
+      this.emit({ type: 'error', error: `Browse failed: ${err}` });
+    }
+  }
+
+  // ── Assignment watching ─────────────────────────────────────────────────
+
+  private watchForAssignment(taskId: string): void {
+    if (!this.running) return;
+    const ms = this.config.watchIntervalMs;
+    const timer = setInterval(async () => {
+      if (!this.running || this.paused) return;
+      try {
+        const detail = await this.bb.getTask(taskId);
+        const a2a = detail.a2aState;
+        if (!a2a) return;
+
+        if (a2a.status === 'assigned') {
+          clearInterval(timer);
+          this.watchTimers.delete(taskId);
+          this.emit({ type: 'task_assigned', taskId });
+          await this.executeTask(taskId, a2a);
+        }
+      } catch {
+        // Retry next tick
+      }
+    }, ms);
+    this.watchTimers.set(taskId, timer);
+  }
+
+  // ── Task execution ──────────────────────────────────────────────────────
+
+  private async executeTask(taskId: string, a2a: A2ATaskState): Promise<void> {
+    const exec = this.executions.get(taskId);
+    if (!exec) return;
+
+    try {
+      exec.status = 'assigned';
+
+      // Accept task — get the ECIES-wrapped AES key
+      const acceptResult = await this.bb.acceptTask(taskId);
+      exec.task = acceptResult.task;
+      this.emit({ type: 'task_accepted', taskId });
+
+      // Get full task detail for the storage root hash
+      const detail = await this.bb.getTask(taskId);
+      const taskHash = detail.taskHash;
+
+      // Decrypt the wrapped key with the worker's private key
+      let instructions = '';
+      if (acceptResult.wrappedKey && taskHash) {
+        const wrappedBytes = this.decodeWrappedKey(acceptResult.wrappedKey);
+        const aesKey = await eciesDecrypt(wrappedBytes, this.wallet!.privateKey);
+
+        // Download ciphertext from storage via REST API
+        const storageResult = await this.bb.downloadBlob(taskHash);
+        const ciphertext = this.hexToBytes(storageResult.data);
+
+        // AES decrypt to get plaintext instructions
+        const plaintext = await aesDecrypt(ciphertext, aesKey);
+        instructions = new TextDecoder().decode(plaintext);
+      }
+
+      exec.status = 'working';
+      this.emit({ type: 'task_working', taskId });
+
+      // Call the user-provided execution handler with decrypted instructions
+      const result = await this.config.executeTask({
+        taskId,
+        task: acceptResult.task,
+        instructions,
+      });
+
+      exec.status = 'submitted';
+      this.emit({ type: 'task_executed', taskId });
+
+      // Submit result
+      const submitResult = await this.bb.submitResult(taskId, result);
+
+      exec.status = 'completed';
+      this.emit({ type: 'task_submitted', taskId, result: submitResult });
+    } catch (err) {
+      exec.status = 'failed';
+      exec.error = String(err);
+      this.emit({ type: 'task_failed', taskId, error: String(err) });
+    }
+  }
+
+  // ── Helpers ─────────────────────────────────────────────────────────────
+
+  private decodeWrappedKey(wrappedKey: Record<string, string>): Uint8Array {
+    // Backend returns wrapped key as hex or base64 in a record
+    const hex = Object.values(wrappedKey)[0];
+    if (!hex) throw new Error('Empty wrapped key');
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(clean.substring(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+  }
+
+  private hexToBytes(hex: string): Uint8Array {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = parseInt(clean.substring(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+  }
+}

package/src/executor/index.ts

@@ -0,0 +1,8 @@
+export {
+  WorkerRuntime,
+  type WorkerRuntimeConfig,
+  type ExecuteTaskHandler,
+  type TaskContext,
+  type TaskExecutionInfo,
+  type WorkerRuntimeEvent,
+} from './WorkerRuntime.js';