@blindmarket/sdk 0.1.4

package/src/chain/BlindEscrowClient.ts

@@ -0,0 +1,182 @@
+import { ethers } from 'ethers';
+import type { Address, Hex, TaskId, TaskStatus, TxReceiptLike } from '../types.js';
+import { BlindEscrowAbi } from './abi/index.js';
+import { wrapChainError } from './errors.js';
+
+const STATUS_BY_INDEX: TaskStatus[] = ['funded', 'assigned', 'submitted', 'verified', 'completed', 'cancelled'];
+
+export interface CreateTaskArgs {
+  taskHash: Hex;
+  token: Address;
+  amount: bigint;
+  category: string;
+  locationZone: string;
+  deadline: bigint;
+}
+
+export interface OnChainTask {
+  taskId: TaskId;
+  agent: Address;
+  worker: Address;
+  token: Address;
+  amount: bigint;
+  taskHash: Hex;
+  evidenceHash: Hex;
+  status: TaskStatus;
+  createdAt: Date;
+  deadline: Date;
+}
+
+/**
+ * Typed ethers v6 wrapper for the BlindEscrow contract. Every state-changing
+ * method awaits one confirmation and returns a TxReceiptLike; every read
+ * returns decoded values. Ethers errors are mapped to ChainError via
+ * wrapChainError().
+ */
+export class BlindEscrowClient {
+  readonly contract: ethers.Contract;
+  readonly address: Address;
+
+  constructor(address: Address, runner: ethers.ContractRunner) {
+    this.address = address;
+    this.contract = new ethers.Contract(address, BlindEscrowAbi, runner);
+  }
+
+  /** Create a task and return its id + receipt. Reads the TaskCreated event for the id. */
+  async createTask(args: CreateTaskArgs): Promise<{ taskId: TaskId; receipt: TxReceiptLike }> {
+    try {
+      const tx = await this.contract.createTask!(
+        args.taskHash,
+        args.token,
+        args.amount,
+        args.category,
+        args.locationZone,
+        args.deadline,
+      );
+      const rec = await tx.wait(1);
+      const taskId = this.extractTaskIdFromReceipt(rec);
+      return { taskId, receipt: toReceipt(rec) };
+    } catch (err) {
+      throw wrapChainError(err, 'createTask');
+    }
+  }
+
+  async assignWorker(taskId: TaskId, worker: Address): Promise<TxReceiptLike> {
+    return this.sendTx('assignWorker', [taskId, worker]);
+  }
+
+  async submitEvidence(taskId: TaskId, evidenceHash: Hex): Promise<TxReceiptLike> {
+    return this.sendTx('submitEvidence', [taskId, evidenceHash]);
+  }
+
+  async completeVerification(taskId: TaskId, passed: boolean): Promise<TxReceiptLike> {
+    return this.sendTx('completeVerification', [taskId, passed]);
+  }
+
+  async cancelTask(taskId: TaskId): Promise<TxReceiptLike> {
+    return this.sendTx('cancelTask', [taskId]);
+  }
+
+  async raiseDispute(taskId: TaskId): Promise<TxReceiptLike> {
+    return this.sendTx('raiseDispute', [taskId]);
+  }
+
+  async resolveDispute(taskId: TaskId, workerFavored: boolean): Promise<TxReceiptLike> {
+    return this.sendTx('resolveDispute', [taskId, workerFavored]);
+  }
+
+  async claimTimeout(taskId: TaskId): Promise<TxReceiptLike> {
+    return this.sendTx('claimTimeout', [taskId]);
+  }
+
+  async getTask(taskId: TaskId): Promise<OnChainTask> {
+    try {
+      const raw = await this.contract.getTask!(taskId);
+      return decodeTask(taskId, raw);
+    } catch (err) {
+      throw wrapChainError(err, 'getTask');
+    }
+  }
+
+  async isTaskExpired(taskId: TaskId): Promise<boolean> {
+    try {
+      return Boolean(await this.contract.isTaskExpired!(taskId));
+    } catch (err) {
+      throw wrapChainError(err, 'isTaskExpired');
+    }
+  }
+
+  async nextTaskId(): Promise<TaskId> {
+    try {
+      return BigInt(await this.contract.nextTaskId!());
+    } catch (err) {
+      throw wrapChainError(err, 'nextTaskId');
+    }
+  }
+
+  async feeBps(): Promise<bigint> {
+    try {
+      return BigInt(await this.contract.feeBps!());
+    } catch (err) {
+      throw wrapChainError(err, 'feeBps');
+    }
+  }
+
+  private async sendTx(method: string, args: unknown[]): Promise<TxReceiptLike> {
+    try {
+      const fn = this.contract[method];
+      if (typeof fn !== 'function') {
+        throw new Error(`unknown contract method: ${method}`);
+      }
+      const tx = await fn(...args);
+      const rec = await tx.wait(1);
+      return toReceipt(rec);
+    } catch (err) {
+      throw wrapChainError(err, method);
+    }
+  }
+
+  private extractTaskIdFromReceipt(receipt: ethers.ContractTransactionReceipt | null): TaskId {
+    if (!receipt) throw new Error('no receipt');
+    const iface = this.contract.interface;
+    for (const log of receipt.logs) {
+      try {
+        const parsed = iface.parseLog({ topics: log.topics as string[], data: log.data });
+        if (parsed?.name === 'TaskCreated') {
+          return BigInt(parsed.args.getValue('taskId'));
+        }
+      } catch {
+        // not our event, skip
+      }
+    }
+    throw new Error('TaskCreated event not found in receipt logs');
+  }
+}
+
+function toReceipt(rec: ethers.ContractTransactionReceipt | null): TxReceiptLike {
+  if (!rec) throw new Error('no receipt');
+  return {
+    hash: rec.hash as Hex,
+    blockNumber: rec.blockNumber,
+    gasUsed: rec.gasUsed,
+  };
+}
+
+function decodeTask(taskId: TaskId, raw: ethers.Result): OnChainTask {
+  // Tuple order from BlindEscrow.getTask(): (agent, worker, token, amount, taskHash,
+  // evidenceHash, status, createdAt, deadline) — verify against contracts/BlindEscrow.sol.
+  const arr = raw as unknown as unknown[];
+  const statusIndex = Number(arr[6]);
+  return {
+    taskId,
+    agent: arr[0] as Address,
+    worker: arr[1] as Address,
+    token: arr[2] as Address,
+    amount: BigInt(arr[3] as bigint | number),
+    taskHash: arr[4] as Hex,
+    evidenceHash: arr[5] as Hex,
+    status: STATUS_BY_INDEX[statusIndex] ?? 'funded',
+    createdAt: new Date(Number(arr[7] as bigint | number) * 1000),
+    deadline: new Date(Number(arr[8] as bigint | number) * 1000),
+  };
+}

package/src/chain/BlindReputationClient.ts

@@ -0,0 +1,55 @@
+import { ethers } from 'ethers';
+import type { Address, Hex, TaskId, TxReceiptLike } from '../types.js';
+import { BlindReputationAbi } from './abi/index.js';
+import { wrapChainError } from './errors.js';
+
+export interface ReputationSnapshot {
+  tasksCompleted: bigint;
+  totalScore: bigint;
+  disputes: bigint;
+  avgScore: number;
+}
+
+export class BlindReputationClient {
+  readonly contract: ethers.Contract;
+  readonly address: Address;
+
+  constructor(address: Address, runner: ethers.ContractRunner) {
+    this.address = address;
+    this.contract = new ethers.Contract(address, BlindReputationAbi, runner);
+  }
+
+  async getReputation(worker: Address): Promise<ReputationSnapshot> {
+    try {
+      const raw = (await this.contract.getReputation!(worker)) as unknown as unknown[];
+      const tasksCompleted = BigInt(raw[0] as bigint | number);
+      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);
+      return { tasksCompleted, totalScore, disputes, avgScore };
+    } catch (err) {
+      throw wrapChainError(err, 'getReputation');
+    }
+  }
+
+  async rate(worker: Address, score: number, taskId: TaskId): Promise<TxReceiptLike> {
+    if (!Number.isInteger(score) || score < 1 || score > 5) {
+      throw wrapChainError(new Error(`score must be integer 1..5, got ${score}`), 'rate');
+    }
+    try {
+      const tx = await this.contract.rate!(worker, score, taskId);
+      const rec = await tx.wait(1);
+      return { hash: rec.hash as Hex, blockNumber: rec.blockNumber, gasUsed: rec.gasUsed };
+    } catch (err) {
+      throw wrapChainError(err, 'rate');
+    }
+  }
+
+  async hasBeenRated(worker: Address, taskId: TaskId): Promise<boolean> {
+    try {
+      return Boolean(await this.contract.hasBeenRated!(worker, taskId));
+    } catch (err) {
+      throw wrapChainError(err, 'hasBeenRated');
+    }
+  }
+}

package/src/chain/ChainClient.ts

@@ -0,0 +1,59 @@
+import { ethers } from 'ethers';
+import type { Signer as SdkSigner } from '../signer/index.js';
+import type { Network } from '../network/index.js';
+import { BlindEscrowClient } from './BlindEscrowClient.js';
+import { BlindReputationClient } from './BlindReputationClient.js';
+import { TaskRegistryClient } from './TaskRegistryClient.js';
+
+export interface ChainClientOptions {
+  network: Network;
+  signer?: SdkSigner;
+  /** If provided, used for reads even when signer is absent. Useful for public queries. */
+  provider?: ethers.Provider;
+}
+
+/**
+ * Bundles typed clients for all three BlindMarket contracts plus the underlying
+ * 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.
+ */
+export class ChainClient {
+  readonly escrow: BlindEscrowClient;
+  readonly registry: TaskRegistryClient;
+  readonly reputation: BlindReputationClient;
+  readonly provider: ethers.Provider;
+  readonly network: Network;
+
+  constructor(opts: ChainClientOptions) {
+    this.network = opts.network;
+    const provider =
+      opts.provider ??
+      (opts.signer && unwrapEthersSigner(opts.signer)?.provider) ??
+      defaultProvider(opts.network);
+    this.provider = provider;
+
+    const runner: ethers.ContractRunner = unwrapEthersSigner(opts.signer) ?? provider;
+    this.escrow = new BlindEscrowClient(opts.network.contracts.escrow, runner);
+    this.registry = new TaskRegistryClient(opts.network.contracts.registry, runner);
+    this.reputation = new BlindReputationClient(opts.network.contracts.reputation, runner);
+  }
+}
+
+/**
+ * If the SDK Signer is an EthersSigner, pull out the inner ethers.Signer
+ * (so ethers.Contract treats it as the transaction runner). Otherwise
+ * returns undefined — writes will fail at the contract layer with a clear
+ * signer-required error, as intended.
+ */
+function unwrapEthersSigner(signer: SdkSigner | undefined): ethers.Signer | undefined {
+  if (!signer) return undefined;
+  const maybe = signer as unknown as { inner?: ethers.Signer };
+  return maybe.inner;
+}
+
+function defaultProvider(network: Network): 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/TaskRegistryClient.ts

@@ -0,0 +1,82 @@
+import { ethers } from 'ethers';
+import type { Address, Hex, TaskId, TxReceiptLike } from '../types.js';
+import { TaskRegistryAbi } from './abi/index.js';
+import { wrapChainError } from './errors.js';
+
+export interface OpenTaskMeta {
+  taskId: TaskId;
+  token: Address;
+  category: string;
+  locationZone: string;
+  reward: bigint;
+  createdAt: Date;
+}
+
+export class TaskRegistryClient {
+  readonly contract: ethers.Contract;
+  readonly address: Address;
+
+  constructor(address: Address, runner: ethers.ContractRunner) {
+    this.address = address;
+    this.contract = new ethers.Contract(address, TaskRegistryAbi, runner);
+  }
+
+  async getTaskMeta(taskId: TaskId): Promise<OpenTaskMeta> {
+    try {
+      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),
+      };
+    } catch (err) {
+      throw wrapChainError(err, 'getTaskMeta');
+    }
+  }
+
+  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));
+    } catch (err) {
+      throw wrapChainError(err, 'getOpenTasks');
+    }
+  }
+
+  async totalTasks(): Promise<bigint> {
+    try {
+      return BigInt(await this.contract.totalTasks!());
+    } catch (err) {
+      throw wrapChainError(err, 'totalTasks');
+    }
+  }
+
+  async openTaskCount(): Promise<bigint> {
+    try {
+      return BigInt(await this.contract.openTaskCount!());
+    } catch (err) {
+      throw wrapChainError(err, 'openTaskCount');
+    }
+  }
+
+  async taskExists(taskId: TaskId): Promise<boolean> {
+    try {
+      return Boolean(await this.contract.taskExists!(taskId));
+    } catch (err) {
+      throw wrapChainError(err, 'taskExists');
+    }
+  }
+
+  async closeTask(taskId: TaskId): Promise<TxReceiptLike> {
+    try {
+      const tx = await this.contract.closeTask!(taskId);
+      const rec = await tx.wait(1);
+      return { hash: rec.hash as Hex, blockNumber: rec.blockNumber, gasUsed: rec.gasUsed };
+    } catch (err) {
+      throw wrapChainError(err, 'closeTask');
+    }
+  }
+}