@blindmarket/sdk 0.1.6 → 0.1.8

package/dist/types.d.ts

@@ -12,7 +12,7 @@ export interface Reward {
     token: Address | TokenSymbol;
     amount: bigint;
 }
-export type TaskStatus = 'funded' | 'assigned' | 'submitted' | 'verified' | 'completed' | 'cancelled';
+export type TaskStatus = 'funded' | 'assigned' | 'submitted' | 'verified' | 'completed' | 'cancelled' | 'disputed';
 export interface TaskMetadata {
     category: string;
     locationZone: string;
@@ -56,3 +56,204 @@ export interface TxReceiptLike {
     gasUsed: bigint;
 }
 export type Awaitable<T> = T | Promise<T>;
+export interface HealthStatus {
+    status: string;
+    timestamp: string;
+}
+export interface PlatformStats {
+    openTasks: number;
+    activeAgents: number;
+    activeValidators: number;
+    totalAgents: number;
+    registeredUsers: number;
+    completedTasks: number;
+    activeWorkers: number;
+}
+export interface OpenTask {
+    id: number;
+    agent: Address;
+    worker?: Address;
+    amount: string;
+    token: Address;
+    category: string;
+    locationZone: string;
+    deadline: number;
+    status: number;
+    taskHash?: Hex;
+}
+export interface CreateTaskTx {
+    unsignedTx: {
+        to: Address;
+        data: Hex;
+        value?: string;
+    };
+}
+export interface TaskDetail extends OpenTask {
+    metadata?: Record<string, unknown>;
+    a2aState?: A2ATaskState;
+}
+export interface A2ATaskState {
+    taskId: string;
+    status: string;
+    executorAddress?: string;
+    acceptedAt?: string;
+    submittedAt?: string;
+    resultData?: Record<string, unknown> | null;
+    verificationResult?: {
+        passed: boolean;
+        reasons: string[];
+        score?: number;
+        breakdown?: Array<{
+            name: string;
+            score: number;
+            weight: number;
+            reason: string;
+            error?: string;
+        }>;
+    };
+    assignTxHash?: Hex;
+    verifyTxHash?: Hex;
+    wrappedKeys?: Record<string, string>;
+}
+export interface ExecutorProfile {
+    address: Address;
+    displayName: string;
+    capabilities: AgentCapability[];
+    publicKey: string;
+    reputation: number;
+    tasksCompleted: number;
+    totalEarnedRaw: string;
+    minReward?: string;
+    preferredCapabilities?: AgentCapability[];
+    registeredAt: string;
+    decayedScore?: number;
+    disputeRatio?: number;
+    avgRating?: number;
+}
+export interface RegisterExecutorInput {
+    address: Address;
+    displayName: string;
+    capabilities: AgentCapability[];
+    publicKey: string;
+    agentCardUrl?: string;
+    mcpEndpointUrl?: string;
+    minReward?: string;
+    preferredCapabilities?: AgentCapability[];
+}
+/** Params for BlindMarket.createAgent() — generates wallet + registers executor in one call. */
+export interface CreateAgentParams {
+    /** Display name for the agent in the marketplace. */
+    displayName: string;
+    /** Capabilities this agent offers. Use AgentCap.DATA_PROCESSING etc. */
+    capabilities: AgentCapability[];
+    /** Which of the above the agent prefers (subset of capabilities). */
+    preferredCapabilities?: AgentCapability[];
+    /** Minimum reward per task (wei string). */
+    minReward?: string;
+    /** Agent card URL for marketplace display. */
+    agentCardUrl?: string;
+    /** MCP endpoint URL for tool-based agents. */
+    mcpEndpointUrl?: string;
+}
+/** Result of BlindMarket.createAgent(). */
+export interface CreateAgentResult {
+    executor: ExecutorProfile;
+    wallet: {
+        address: Address;
+        publicKey: string;
+        privateKey: string;
+    };
+}
+export interface DeployedAgentInfo {
+    id: string;
+    name: string;
+    ownerAddress: Address;
+    walletAddress: Address;
+    publicKey: string;
+    status: string;
+    provider: string;
+    model: string;
+    capabilities: AgentCapability[];
+    inftTokenId?: number;
+    deployedAt: string;
+    lastActiveAt?: string;
+    minReward?: string;
+}
+export interface AgentWalletInfo {
+    walletAddress: Address;
+    publicKey: string;
+}
+export interface ReputationInfo {
+    address: Address;
+    onChainScore: number;
+    decayedScore: number;
+    totalTasks: number;
+    disputesLost: number;
+    disputeRatio: number;
+}
+export interface LeaderboardEntry extends ReputationInfo {
+    rank: number;
+    displayName?: string;
+}
+export interface StorageUploadResult {
+    rootHash: RootHash;
+    size: number;
+}
+export interface Message {
+    id: number;
+    taskId: string;
+    fromAddress: Address;
+    toAddress: Address;
+    content: string;
+    read: boolean;
+    createdAt: string;
+}
+export interface AgentSearchResult {
+    address: Address;
+    displayName: string;
+    capabilities: string[];
+    avgRating: number;
+    reviewCount: number;
+    badgeCount: number;
+    reputation: number;
+}
+export interface TaskTemplate {
+    id: number;
+    title: string;
+    description: string;
+    category: string;
+    instructions: string;
+    verificationCriteria: Record<string, unknown>;
+    requiredCapabilities?: string[];
+    estimatedReward?: string;
+}
+export interface VerifyTaskInput {
+    taskId: number;
+    taskCategory: string;
+    taskRequirements: string;
+    evidenceSummary: string;
+}
+/** Dot-notation access to valid capability strings. */
+export declare const AgentCap: {
+    readonly DATA_PROCESSING: "data_processing";
+    readonly WEB_RESEARCH: "web_research";
+    readonly CODE_EXECUTION: "code_execution";
+    readonly CONTENT_GENERATION: "content_generation";
+    readonly API_INTEGRATION: "api_integration";
+    readonly TEXT_ANALYSIS: "text_analysis";
+    readonly TRANSLATION: "translation";
+    readonly SUMMARIZATION: "summarization";
+    readonly IMAGE_ANALYSIS: "image_analysis";
+    readonly DOCUMENT_PROCESSING: "document_processing";
+    readonly MATH_COMPUTATION: "math_computation";
+    readonly DATA_EXTRACTION: "data_extraction";
+    readonly REPORT_GENERATION: "report_generation";
+    readonly CODE_REVIEW: "code_review";
+    readonly TESTING: "testing";
+    readonly SCHEDULING: "scheduling";
+    readonly EMAIL_DRAFTING: "email_drafting";
+    readonly SOCIAL_MEDIA: "social_media";
+    readonly MARKET_RESEARCH: "market_research";
+    readonly COMPETITIVE_ANALYSIS: "competitive_analysis";
+};
+export type AgentCapability = typeof AgentCap[keyof typeof AgentCap];

package/dist/types.js

@@ -1 +1,24 @@
-export {};
+// ── Agent capabilities ───────────────────────────────────────────────────────
+/** Dot-notation access to valid capability strings. */
+export const AgentCap = {
+    DATA_PROCESSING: 'data_processing',
+    WEB_RESEARCH: 'web_research',
+    CODE_EXECUTION: 'code_execution',
+    CONTENT_GENERATION: 'content_generation',
+    API_INTEGRATION: 'api_integration',
+    TEXT_ANALYSIS: 'text_analysis',
+    TRANSLATION: 'translation',
+    SUMMARIZATION: 'summarization',
+    IMAGE_ANALYSIS: 'image_analysis',
+    DOCUMENT_PROCESSING: 'document_processing',
+    MATH_COMPUTATION: 'math_computation',
+    DATA_EXTRACTION: 'data_extraction',
+    REPORT_GENERATION: 'report_generation',
+    CODE_REVIEW: 'code_review',
+    TESTING: 'testing',
+    SCHEDULING: 'scheduling',
+    EMAIL_DRAFTING: 'email_drafting',
+    SOCIAL_MEDIA: 'social_media',
+    MARKET_RESEARCH: 'market_research',
+    COMPETITIVE_ANALYSIS: 'competitive_analysis',
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blindmarket/sdk",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "BlindMarket SDK — deploy agents, assign workers, verify evidence",
   "author": "BlindMarket Team",
   "license": "MIT",
@@ -21,7 +21,14 @@
     "bounty",
     "blockchain",
     "encrypted",
-    "agent-to-human"
+    "agent-to-human",
+    "mcp",
+    "model-context-protocol",
+    "openai-tools",
+    "agent-sdk",
+    "claude",
+    "langchain",
+    "vercel-ai-sdk"
   ],
   "type": "module",
   "main": "./dist/index.js",
@@ -30,6 +37,10 @@
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
+    },
+    "./tools": {
+      "import": "./dist/tools/index.js",
+      "types": "./dist/tools/index.d.ts"
     }
   },
   "scripts": {

package/src/chain/BlindEscrowClient.ts

@@ -3,7 +3,7 @@ import type { Address, Hex, TaskId, TaskStatus, TxReceiptLike } from '../types.j
 import { BlindEscrowAbi } from './abi/index.js';
 import { wrapChainError } from './errors.js';
 
-const STATUS_BY_INDEX: TaskStatus[] = ['funded', 'assigned', 'submitted', 'verified', 'completed', 'cancelled'];
+const STATUS_BY_INDEX: TaskStatus[] = ['funded', 'assigned', 'submitted', 'verified', 'completed', 'cancelled', 'disputed'];
 
 export interface CreateTaskArgs {
   taskHash: Hex;
@@ -23,6 +23,8 @@ export interface OnChainTask {
   taskHash: Hex;
   evidenceHash: Hex;
   status: TaskStatus;
+  category: string;
+  locationZone: string;
   createdAt: Date;
   deadline: Date;
 }
@@ -45,6 +47,10 @@ export class BlindEscrowClient {
   /** 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 overrides: ethers.Overrides = {};
+      if (args.token === '0x0000000000000000000000000000000000000000') {
+        overrides.value = args.amount;
+      }
       const tx = await this.contract.createTask!(
         args.taskHash,
         args.token,
@@ -52,6 +58,7 @@ export class BlindEscrowClient {
         args.category,
         args.locationZone,
         args.deadline,
+        overrides,
       );
       const rec = await tx.wait(1);
       const taskId = this.extractTaskIdFromReceipt(rec);
@@ -163,10 +170,15 @@ function toReceipt(rec: ethers.ContractTransactionReceipt | null): TxReceiptLike
 }
 
 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.
+  // Live Task struct (12 fields) from BlindEscrow.getTask(): agent, worker,
+  // token, amount, taskHash, evidenceHash, status, category, locationZone,
+  // createdAt, deadline, submissionAttempts. The old decode read createdAt from
+  // arr[7] (actually category) and deadline from arr[8] (actually locationZone),
+  // yielding Invalid Date and discarding category/locationZone.
   const arr = raw as unknown as unknown[];
   const statusIndex = Number(arr[6]);
+  const status = STATUS_BY_INDEX[statusIndex];
+  if (!status) throw new Error(`BlindEscrow.getTask returned unknown status index ${statusIndex}`);
   return {
     taskId,
     agent: arr[0] as Address,
@@ -175,8 +187,10 @@ function decodeTask(taskId: TaskId, raw: ethers.Result): OnChainTask {
     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),
+    status,
+    category: arr[7] as string,
+    locationZone: arr[8] as string,
+    createdAt: new Date(Number(arr[9] as bigint | number) * 1000),
+    deadline: new Date(Number(arr[10] as bigint | number) * 1000),
   };
 }

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,
+  });
+}