@blindmarket/sdk 0.1.7 → 0.1.8

package/src/chain/BlindReputationClient.ts

@@ -5,8 +5,11 @@ import { wrapChainError } from './errors.js';
 
 export interface ReputationSnapshot {
   tasksCompleted: bigint;
+  /** Raw on-chain value. NOTE: despite the name, the contract returns the
+   *  average rating already scaled ×100 (450 = 4.50), NOT a cumulative sum. */
   totalScore: bigint;
   disputes: bigint;
+  /** 0–5 average rating. */
   avgScore: number;
 }
 
@@ -23,9 +26,11 @@ export class BlindReputationClient {
     try {
       const raw = (await this.contract.getReputation!(worker)) as unknown as unknown[];
       const tasksCompleted = BigInt(raw[0] as bigint | number);
+      // raw[1] is already avgScore × 100 (contract getReputation returns the
+      // average scaled ×100, "450 = 4.50") — divide by 100 only, NOT by tasks.
       const totalScore = BigInt(raw[1] as bigint | number);
       const disputes = BigInt(raw[2] as bigint | number);
-      const avgScore = tasksCompleted === 0n ? 0 : Number(totalScore) / Number(tasksCompleted);
+      const avgScore = Number(totalScore) / 100;
       return { tasksCompleted, totalScore, disputes, avgScore };
     } catch (err) {
       throw wrapChainError(err, 'getReputation');

package/src/chain/ChainClient.ts

@@ -1,6 +1,7 @@
 import { ethers } from 'ethers';
 import type { Signer as SdkSigner } from '../signer/index.js';
-import type { Network } from '../network/index.js';
+import type { EVMNetwork } from './domain-types.js';
+import type { Network } from './domain-types.js';
 import { BlindEscrowClient } from './BlindEscrowClient.js';
 import { BlindReputationClient } from './BlindReputationClient.js';
 import { TaskRegistryClient } from './TaskRegistryClient.js';
@@ -17,15 +18,20 @@ export interface ChainClientOptions {
  * ethers runner. Reads use provider (or signer's provider); writes require a
  * signer. To keep the SDK's Signer abstraction decoupled from ethers at the
  * call sites, we unwrap an EthersSigner's inner ethers.Signer lazily here.
+ *
+ * Only supports EVM networks.
  */
 export class ChainClient {
   readonly escrow: BlindEscrowClient;
   readonly registry: TaskRegistryClient;
   readonly reputation: BlindReputationClient;
   readonly provider: ethers.Provider;
-  readonly network: Network;
+  readonly network: EVMNetwork;
 
   constructor(opts: ChainClientOptions) {
+    if (opts.network.chainType !== 'evm') {
+      throw new Error(`ChainClient requires an EVM network, got ${opts.network.chainType}`);
+    }
     this.network = opts.network;
     const provider =
       opts.provider ??
@@ -52,7 +58,7 @@ function unwrapEthersSigner(signer: SdkSigner | undefined): ethers.Signer | unde
   return maybe.inner;
 }
 
-function defaultProvider(network: Network): ethers.Provider {
+function defaultProvider(network: EVMNetwork): ethers.Provider {
   const url = network.rpc[0];
   if (!url) throw new Error(`network ${network.name} has no RPC endpoint configured`);
   return new ethers.JsonRpcProvider(url, { chainId: Number(network.chainId), name: network.name });

package/src/chain/IBlindMarketChain.ts

@@ -0,0 +1,109 @@
+import type {
+  CreateTaskParams,
+  DomainReputation,
+  DomainTask,
+  DomainTaskMeta,
+  DomainTxReceipt,
+  Network,
+} from './domain-types.js';
+
+/**
+ * Chain-agnostic interface for BlindMarket on-chain operations.
+ *
+ * Every supported blockchain provides an adapter that implements this interface,
+ * translating domain operations into chain-native contract calls. Consumers
+ * (backend, agents, CLI) work against this interface and never need to know
+ * which chain they're talking to.
+ */
+export interface IBlindMarketChain {
+  // ── Chain identity ──────────────────────────────────────────────────────
+
+  /** The resolved network config this adapter is connected to. */
+  readonly network: Network;
+
+  /** The address of the active signer. */
+  getAddress(): Promise<string>;
+
+  // ── Task lifecycle (BlindEscrow equivalent) ─────────────────────────────
+
+  /**
+   * Create a new task with escrowed funds.
+   * Returns the assigned task ID and receipt.
+   */
+  createTask(params: CreateTaskParams): Promise<{ taskId: bigint; receipt: DomainTxReceipt }>;
+
+  /** Assign a worker to a funded task. Caller must be the task agent. */
+  assignWorker(taskId: bigint, worker: string): Promise<DomainTxReceipt>;
+
+  /** Submit an evidence hash for an assigned task. Caller must be the worker. */
+  submitEvidence(taskId: bigint, evidenceHash: string): Promise<DomainTxReceipt>;
+
+  /** Complete verification for a submitted task (called by the verifier). */
+  completeVerification(taskId: bigint, passed: boolean): Promise<DomainTxReceipt>;
+
+  /** Cancel a funded/assigned task and return escrow to the agent. */
+  cancelTask(taskId: bigint): Promise<DomainTxReceipt>;
+
+  /** Claim escrow after timeout expiry (agent-side). */
+  claimTimeout(taskId: bigint): Promise<DomainTxReceipt>;
+
+  /** Raise a dispute on a task. */
+  raiseDispute(taskId: bigint): Promise<DomainTxReceipt>;
+
+  /** Resolve a dispute (admin only). */
+  resolveDispute(taskId: bigint, workerFavored: boolean): Promise<DomainTxReceipt>;
+
+  /** Read full on-chain task state. */
+  getTask(taskId: bigint): Promise<DomainTask>;
+
+  /** Check whether a task's deadline has passed. */
+  isTaskExpired(taskId: bigint): Promise<boolean>;
+
+  // ── Task discovery (TaskRegistry equivalent) ────────────────────────────
+
+  /** Publish task metadata to the on-chain discovery index. */
+  publishTask(taskId: bigint, meta: Omit<DomainTaskMeta, 'taskId'> & { taskId?: bigint }): Promise<DomainTxReceipt>;
+
+  /** Remove a task from the discovery index (called on assignment/completion). */
+  closeTask(taskId: bigint): Promise<DomainTxReceipt>;
+
+  /** Get a page of open task IDs from the discovery index. */
+  getOpenTasks(offset: bigint, limit: bigint): Promise<DomainTaskMeta[]>;
+
+  /** Count of currently open tasks. */
+  openTaskCount(): Promise<bigint>;
+
+  /** Total tasks ever published. */
+  totalTasks(): Promise<bigint>;
+
+  // ── Reputation (BlindReputation equivalent) ─────────────────────────────
+
+  /** Rate a worker after task completion (score 1-5). */
+  rateWorker(worker: string, score: number, taskId: bigint): Promise<DomainTxReceipt>;
+
+  /** Record a dispute against a worker. */
+  recordDispute(worker: string, taskId: bigint): Promise<DomainTxReceipt>;
+
+  /** Fetch on-chain reputation for a worker. */
+  getReputation(worker: string): Promise<DomainReputation>;
+
+  /** Check if a worker has already been rated for a given task. */
+  hasBeenRated(worker: string, taskId: bigint): Promise<boolean>;
+
+  // ── Agent identity (INFT equivalent) ────────────────────────────────────
+
+  /** Mint an agent identity token. Returns the token ID and receipt. */
+  mintAgent(params: {
+    to: string;
+    encryptedURI: string;
+    metadataHash: string;
+  }): Promise<{ tokenId: bigint; receipt: DomainTxReceipt }>;
+
+  /** Read the encrypted metadata URI for an agent token. */
+  getEncryptedURI(tokenId: bigint): Promise<string>;
+
+  // ── Queries ──────────────────────────────────────────────────────────────
+
+  /** Get native balance for an address. */
+  getBalance(address: string): Promise<bigint>;
+}

package/src/chain/TaskRegistryClient.ts

@@ -5,11 +5,12 @@ import { wrapChainError } from './errors.js';
 
 export interface OpenTaskMeta {
   taskId: TaskId;
-  token: Address;
+  agent: Address;
   category: string;
   locationZone: string;
   reward: bigint;
   createdAt: Date;
+  isOpen: boolean;
 }
 
 export class TaskRegistryClient {
@@ -23,14 +24,19 @@ export class TaskRegistryClient {
 
   async getTaskMeta(taskId: TaskId): Promise<OpenTaskMeta> {
     try {
+      // Live TaskMeta struct order: taskId, agent, category, locationZone,
+      // reward, createdAt, isOpen (7 fields). The old decode was off by one
+      // field from the start (token/agent/category/locationZone), so BigInt() on
+      // the locationZone string threw on every real task.
       const raw = (await this.contract.getTaskMeta!(taskId)) as unknown as unknown[];
       return {
         taskId,
-        token: raw[0] as Address,
-        category: raw[1] as string,
-        locationZone: raw[2] as string,
-        reward: BigInt(raw[3] as bigint | number),
-        createdAt: new Date(Number(raw[4] as bigint | number) * 1000),
+        agent: raw[1] as Address,
+        category: raw[2] as string,
+        locationZone: raw[3] as string,
+        reward: BigInt(raw[4] as bigint | number),
+        createdAt: new Date(Number(raw[5] as bigint | number) * 1000),
+        isOpen: Boolean(raw[6]),
       };
     } catch (err) {
       throw wrapChainError(err, 'getTaskMeta');
@@ -39,8 +45,11 @@ export class TaskRegistryClient {
 
   async getOpenTasks(offset: bigint, limit: bigint): Promise<TaskId[]> {
     try {
-      const ids = (await this.contract.getOpenTasks!(offset, limit)) as unknown as unknown[];
-      return ids.map((x) => BigInt(x as bigint | number));
+      // getOpenTasks returns TaskMeta[] structs, NOT raw ids — extract .taskId
+      // (field 0) from each. BigInt()-ing the whole struct tuple threw on any
+      // non-empty page.
+      const metas = (await this.contract.getOpenTasks!(offset, limit)) as unknown as any[];
+      return metas.map((m) => BigInt((m?.taskId ?? m?.[0]) as bigint | number));
     } catch (err) {
       throw wrapChainError(err, 'getOpenTasks');
     }

package/src/chain/createChainAdapter.ts

@@ -0,0 +1,40 @@
+import type { IBlindMarketChain } from './IBlindMarketChain.js';
+import { EVMChainAdapter } from './evm/EVMChainAdapter.js';
+import { resolveNetwork } from '../network/resolve.js';
+import type { Network, NetworkName as PresetName } from '../network/index.js';
+import type { EthersSigner } from '../signer/EthersSigner.js';
+
+/**
+ * Options for creating a chain adapter via the factory.
+ *
+ * The factory chooses the correct adapter based on `network.chainType`.
+ */
+export interface CreateChainAdapterOptions {
+  network: Network | PresetName;
+  signer?: EthersSigner;
+}
+
+/**
+ * Factory: create the correct IBlindMarketChain adapter for the given network.
+ *
+ * @example
+ * ```ts
+ * // EVM (0G)
+ * const chain = createChainAdapter({
+ *   network: 'og-testnet',
+ *   signer: new PrivateKeySigner(privkey, provider),
+ * });
+ * ```
+ */
+export function createChainAdapter(opts: CreateChainAdapterOptions): IBlindMarketChain {
+  const network = resolveNetwork(opts.network);
+
+  if (network.chainType !== 'evm') {
+    throw new Error(`Unsupported chain type: ${network.chainType}. Only EVM (0G) is supported.`);
+  }
+
+  return new EVMChainAdapter({
+    network,
+    signer: opts.signer,
+  });
+}

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';