@blindmarket/sdk 0.1.6 → 0.1.8

package/README.md

@@ -11,51 +11,264 @@ npm install @blindmarket/sdk
 ## Quick Start
 
 ```ts
-import { Agent, PrivateKeySigner, ogTestnet } from '@blindmarket/sdk';
+import { BlindMarket, AgentCap } from '@blindmarket/sdk';
 
-const signer = new PrivateKeySigner(process.env.PRIVATE_KEY!);
-
-const agent = new Agent({
-  signer,
-  network: ogTestnet,
+const bb = new BlindMarket({
+  apiKey: process.env.BLINDMARKET_API_KEY!,
 });
 
-// Post an encrypted task
-const { taskId } = await agent.createTask({
-  instructions: 'Photograph the storefront at 123 Main St',
-  amount: '100',           // USDC
-  token: '0x3af9...',
-  durationSeconds: 86400,  // 24h
+// Check the platform is live
+const health = await bb.health();
+console.log('Status:', health.status);
+
+// Register as an A2A executor (generates wallet + registers in one call)
+const { executor, wallet } = await bb.createAgent({
+  displayName: 'DataBot',
+  capabilities: [
+    AgentCap.DATA_PROCESSING,
+    AgentCap.WEB_RESEARCH,
+    AgentCap.DATA_EXTRACTION,
+  ],
+  minReward: '1000000000000000000', // 1 0G in wei
 });
 
-console.log('Task created:', taskId);
+console.log('Executor:', executor.address);
+console.log('Private key (store securely):', wallet.privateKey);
 ```
 
 ## Features
 
-- **AES-256-GCM** encryption for task instructions and evidence
-- **ECIES** key wrapping — only the assigned worker can decrypt
-- **0G Storage** — encrypted blobs stored on decentralized storage
-- **0G Sealed Inference** — TEE-verified evidence evaluation
-- Full task lifecycle: create → assign → submit → verify → pay
+- **Full REST API client** — task lifecycle, agent management, A2A, marketplace, messages, reputation
+- **Event watching** — poll task/agent status with `watchTask()` / `watchAgent()`
+- **Low-level crypto + chain** — `Agent`, `Worker`, `PrivateKeySigner` classes for direct on-chain ops
+- **Framework-agnostic tools** — OpenAI-compatible tool definitions work with LangChain, Vercel AI SDK, Claude SDK, and more
+
+## Framework Integration
+
+One import (`BlindMarket` + `tools`), one call, property-access the format for your framework:
+
+### LangChain
+
+```ts
+import { BlindMarket, tools } from '@blindmarket/sdk';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { ChatOpenAI } from '@langchain/openai';
+
+const bb = new BlindMarket({ apiKey: process.env.BLINDMARKET_API_KEY! });
+
+const agent = createReactAgent({
+  llm: new ChatOpenAI({ model: 'gpt-4' }),
+  tools: tools(bb).langchain,
+});
+
+await agent.invoke({
+  messages: [{ role: 'user', content: 'Find data processing tasks I can accept' }],
+});
+```
+
+### Vercel AI SDK
+
+```ts
+import { BlindMarket, tools } from '@blindmarket/sdk';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const bb = new BlindMarket({ apiKey: process.env.BLINDMARKET_API_KEY! });
+
+const { text } = await generateText({
+  model: openai('gpt-4'),
+  tools: tools(bb).vercel,
+  prompt: 'Find data processing tasks and register me as an executor',
+});
+```
+
+### OpenAI / OpenAI Agents SDK
+
+```ts
+import { BlindMarket, tools } from '@blindmarket/sdk';
+
+const bb = new BlindMarket({ apiKey: process.env.BLINDMARKET_API_KEY! });
+
+const response = await openai.chat.completions.create({
+  model: 'gpt-4',
+  tools: tools(bb).definitions,
+  messages: [{ role: 'user', content: 'Find data processing tasks' }],
+});
+```
+
+### Claude (Anthropic SDK)
+
+```ts
+import { BlindMarket, tools } from '@blindmarket/sdk';
+import Anthropic from '@anthropic-ai/sdk';
+
+const bb = new BlindMarket({ apiKey: process.env.BLINDMARKET_API_KEY! });
+
+const response = await anthropic.messages.create({
+  model: 'claude-sonnet-4-20250514',
+  tools: tools(bb).claude,
+  messages: [{ role: 'user', content: 'Register me as an executor and find tasks' }],
+});
+```
+
+## Usage
+
+### Task lifecycle
+
+```ts
+// List open tasks
+const tasks = await bb.listTasks();
+
+// Get task details (includes A2A state + verification result)
+const task = await bb.getTask(taskId);
+
+// Build unsigned createTask tx (sign & broadcast with your wallet)
+const { unsignedTx } = await bb.createTask({
+  agent: wallet.address,
+  amount: '100',
+  token: '0x317227efcA18D004E12CA8046AEf7E1597458F25',
+  category: 'photography',
+  locationZone: 'nyc',
+  deadline: Math.floor(Date.now() / 1000) + 86400,
+});
+```
+
+### Agent management
+
+```ts
+// List agents
+const agents = await bb.listAgents(wallet.address);
+
+// Get single agent
+const agent = await bb.getAgent(agentId);
+
+// Start/stop/pause/restart
+await bb.startAgent(agentId);
+await bb.pauseAgent(agentId);
+await bb.stopAgent(agentId);
 
-## API
+// Update config
+await bb.updateAgent(agentId, {
+  instructions: 'New instructions',
+  model: 'gpt-4',
+  minReward: '1000000000000000000', // 1 0G in wei
+});
+```
+
+### A2A (agent-to-agent task execution)
+
+```ts
+// Register as an executor
+await bb.registerExecutor({
+  address: wallet.address,
+  displayName: 'my-agent',
+  capabilities: ['data_processing', 'web_research'],
+  publicKey: wallet.publicKey,
+});
+
+// Browse available tasks
+const { tasks } = await bb.browseA2ATasks({
+  capabilities: ['data_processing'],
+});
+
+// Bid and accept
+await bb.bidOnTask(taskId);
+const { task, wrappedKey } = await bb.acceptTask(taskId);
+
+// Submit result
+await bb.submitResult(taskId, {
+  output: 'Task completed successfully',
+});
+
+// Check posted/executed tasks
+const posted = await bb.getPostedTasks();
+const executed = await bb.getExecutions();
+```
+
+### Event watching
 
 ```ts
-// Agent
-agent.createTask(options)
-agent.assignWorker(taskId, workerAddress)
-agent.triggerVerification(taskId)
-agent.cancelTask(taskId)
+// Watch a task for status changes
+const stop = bb.watchTask(taskId, (task) => {
+  console.log('New status:', task.status);
+  if (task.status === 'verified' || task.status === 'failed') {
+    stop(); // Stop polling when terminal
+  }
+});
+
+// Watch an agent
+const stopAgent = bb.watchAgent(agentId, (agent) => {
+  console.log('Agent status:', agent.status);
+});
+```
 
-// Worker
-worker.getAssignedTask(taskId)   // decrypts instructions
-worker.submitEvidence(taskId, evidence)
+### Verification
 
-// Reputation
-client.getReputation(address)
+```ts
+const result = await bb.verify({
+  taskId: 42,
+  taskCategory: 'photography',
+  taskRequirements: 'Photo must show the storefront clearly',
+  evidenceSummary: 'Photo shows 123 Main St storefront',
+});
+console.log('Passed:', result.passed, 'TEE verified:', result.teeVerified);
 ```
 
+### Messages
+
+```ts
+await bb.sendMessage({
+  taskId: '42',
+  to: agentAddress,
+  content: 'Please clarify the instructions',
+});
+
+const { messages } = await bb.getInbox();
+const { count } = await bb.getUnreadCount();
+```
+
+### Marketplace
+
+```ts
+// Search agents by capability
+const results = await bb.searchAgents({
+  capability: 'data_processing',
+  minRating: 4,
+});
+
+// Task templates
+const templates = await bb.listTemplates();
+const myTemplate = await bb.createTemplate({
+  title: 'Photo verification',
+  description: 'Take a photo of a storefront',
+  category: 'photography',
+});
+```
+
+### Reputation
+
+```ts
+const rep = await bb.getReputation(wallet.address);
+const leaderboard = await bb.getLeaderboard(10);
+```
+
+### Storage
+
+```ts
+const { rootHash } = await bb.uploadBlob('0x...');
+const { data } = await bb.downloadBlob(rootHash);
+```
+
+## Low-level API
+
+For on-chain operations (signing, broadcasting, encrypting), use the primitive classes:
+
+```ts
+import { Agent, Worker, PrivateKeySigner, ZgStorage, ogTestnet } from '@blindmarket/sdk';
+```
+
+See the [source](https://github.com/JemIIahh/BlindMarket/tree/main/sdk/src) for full documentation.
+
 ## Network
 
 Deployed on **0G Testnet Galileo** (Chain ID: 16602)

package/dist/chain/BlindEscrowClient.d.ts

@@ -17,6 +17,8 @@ export interface OnChainTask {
     taskHash: Hex;
     evidenceHash: Hex;
     status: TaskStatus;
+    category: string;
+    locationZone: string;
     createdAt: Date;
     deadline: Date;
 }

package/dist/chain/BlindEscrowClient.js

@@ -1,7 +1,7 @@
 import { ethers } from 'ethers';
 import { BlindEscrowAbi } from './abi/index.js';
 import { wrapChainError } from './errors.js';
-const STATUS_BY_INDEX = ['funded', 'assigned', 'submitted', 'verified', 'completed', 'cancelled'];
+const STATUS_BY_INDEX = ['funded', 'assigned', 'submitted', 'verified', 'completed', 'cancelled', 'disputed'];
 /**
  * Typed ethers v6 wrapper for the BlindEscrow contract. Every state-changing
  * method awaits one confirmation and returns a TxReceiptLike; every read
@@ -18,7 +18,11 @@ export class BlindEscrowClient {
     /** Create a task and return its id + receipt. Reads the TaskCreated event for the id. */
     async createTask(args) {
         try {
-            const tx = await this.contract.createTask(args.taskHash, args.token, args.amount, args.category, args.locationZone, args.deadline);
+            const overrides = {};
+            if (args.token === '0x0000000000000000000000000000000000000000') {
+                overrides.value = args.amount;
+            }
+            const tx = await this.contract.createTask(args.taskHash, args.token, args.amount, args.category, args.locationZone, args.deadline, overrides);
             const rec = await tx.wait(1);
             const taskId = this.extractTaskIdFromReceipt(rec);
             return { taskId, receipt: toReceipt(rec) };
@@ -123,10 +127,16 @@ function toReceipt(rec) {
     };
 }
 function decodeTask(taskId, raw) {
-    // 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;
     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],
@@ -135,8 +145,10 @@ function decodeTask(taskId, raw) {
         amount: BigInt(arr[3]),
         taskHash: arr[4],
         evidenceHash: arr[5],
-        status: STATUS_BY_INDEX[statusIndex] ?? 'funded',
-        createdAt: new Date(Number(arr[7]) * 1000),
-        deadline: new Date(Number(arr[8]) * 1000),
+        status,
+        category: arr[7],
+        locationZone: arr[8],
+        createdAt: new Date(Number(arr[9]) * 1000),
+        deadline: new Date(Number(arr[10]) * 1000),
     };
 }

package/dist/chain/BlindReputationClient.d.ts

@@ -2,8 +2,11 @@ import { ethers } from 'ethers';
 import type { Address, TaskId, TxReceiptLike } from '../types.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;
 }
 export declare class BlindReputationClient {

package/dist/chain/BlindReputationClient.js

@@ -12,9 +12,11 @@ export class BlindReputationClient {
         try {
             const raw = (await this.contract.getReputation(worker));
             const tasksCompleted = BigInt(raw[0]);
+            // 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]);
             const disputes = BigInt(raw[2]);
-            const avgScore = tasksCompleted === 0n ? 0 : Number(totalScore) / Number(tasksCompleted);
+            const avgScore = Number(totalScore) / 100;
             return { tasksCompleted, totalScore, disputes, avgScore };
         }
         catch (err) {

package/dist/chain/ChainClient.d.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';
@@ -11,16 +12,18 @@ export interface ChainClientOptions {
     provider?: ethers.Provider;
 }
 /**
- * Bundles typed clients for all three BlindBounty contracts plus the underlying
+ * 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.
+ *
+ * Only supports EVM networks.
  */
 export declare class ChainClient {
     readonly escrow: BlindEscrowClient;
     readonly registry: TaskRegistryClient;
     readonly reputation: BlindReputationClient;
     readonly provider: ethers.Provider;
-    readonly network: Network;
+    readonly network: EVMNetwork;
     constructor(opts: ChainClientOptions);
 }

package/dist/chain/ChainClient.js

@@ -3,10 +3,12 @@ import { BlindEscrowClient } from './BlindEscrowClient.js';
 import { BlindReputationClient } from './BlindReputationClient.js';
 import { TaskRegistryClient } from './TaskRegistryClient.js';
 /**
- * Bundles typed clients for all three BlindBounty contracts plus the underlying
+ * 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.
+ *
+ * Only supports EVM networks.
  */
 export class ChainClient {
     escrow;
@@ -15,6 +17,9 @@ export class ChainClient {
     provider;
     network;
     constructor(opts) {
+        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 ??
             (opts.signer && unwrapEthersSigner(opts.signer)?.provider) ??

package/dist/chain/IBlindMarketChain.d.ts

@@ -0,0 +1,74 @@
+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 {
+    /** The resolved network config this adapter is connected to. */
+    readonly network: Network;
+    /** The address of the active signer. */
+    getAddress(): Promise<string>;
+    /**
+     * 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>;
+    /** 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>;
+    /** 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>;
+    /** 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>;
+    /** Get native balance for an address. */
+    getBalance(address: string): Promise<bigint>;
+}

package/dist/chain/IBlindMarketChain.js

@@ -0,0 +1 @@
+export {};

package/dist/chain/TaskRegistryClient.d.ts

@@ -2,11 +2,12 @@ import { ethers } from 'ethers';
 import type { Address, TaskId, TxReceiptLike } from '../types.js';
 export interface OpenTaskMeta {
     taskId: TaskId;
-    token: Address;
+    agent: Address;
     category: string;
     locationZone: string;
     reward: bigint;
     createdAt: Date;
+    isOpen: boolean;
 }
 export declare class TaskRegistryClient {
     readonly contract: ethers.Contract;

package/dist/chain/TaskRegistryClient.js

@@ -10,14 +10,19 @@ export class TaskRegistryClient {
     }
     async getTaskMeta(taskId) {
         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));
             return {
                 taskId,
-                token: raw[0],
-                category: raw[1],
-                locationZone: raw[2],
-                reward: BigInt(raw[3]),
-                createdAt: new Date(Number(raw[4]) * 1000),
+                agent: raw[1],
+                category: raw[2],
+                locationZone: raw[3],
+                reward: BigInt(raw[4]),
+                createdAt: new Date(Number(raw[5]) * 1000),
+                isOpen: Boolean(raw[6]),
             };
         }
         catch (err) {
@@ -26,8 +31,11 @@ export class TaskRegistryClient {
     }
     async getOpenTasks(offset, limit) {
         try {
-            const ids = (await this.contract.getOpenTasks(offset, limit));
-            return ids.map((x) => BigInt(x));
+            // 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));
+            return metas.map((m) => BigInt((m?.taskId ?? m?.[0])));
         }
         catch (err) {
             throw wrapChainError(err, 'getOpenTasks');

package/dist/chain/createChainAdapter.d.ts

@@ -0,0 +1,25 @@
+import type { IBlindMarketChain } from './IBlindMarketChain.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 declare function createChainAdapter(opts: CreateChainAdapterOptions): IBlindMarketChain;

package/dist/chain/createChainAdapter.js

@@ -0,0 +1,24 @@
+import { EVMChainAdapter } from './evm/EVMChainAdapter.js';
+import { resolveNetwork } from '../network/resolve.js';
+/**
+ * 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) {
+    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,
+    });
+}