@blindmarket/sdk 0.7.0 → 0.9.0

package/dist/network/presets.d.ts

@@ -23,7 +23,7 @@ export declare const networks: {
         readonly name: "0g-mainnet";
         readonly chainType: "evm";
         readonly chainId: 16661;
-        readonly rpc: ["https://evmrpc.0g.ai"];
+        readonly rpc: ["https://0g-rpc.publicnode.com"];
         readonly contracts: {
             readonly escrow: "0x3d0374963DaaD43e31d42373eb11156A8e8ce2Ff";
             readonly registry: "0x9CCF9c196006B573FaA9C9c9CebDd1296dbd5cE0";

package/dist/network/presets.js

@@ -19,7 +19,7 @@ export const networks = {
         name: '0g-mainnet',
         chainType: 'evm',
         chainId: 16661,
-        rpc: ['https://evmrpc.0g.ai'],
+        rpc: ['https://0g-rpc.publicnode.com'],
         contracts: {
             escrow: '0x3d0374963DaaD43e31d42373eb11156A8e8ce2Ff',
             registry: '0x9CCF9c196006B573FaA9C9c9CebDd1296dbd5cE0',

package/dist/onchain.d.ts

@@ -13,12 +13,16 @@ import { ethers } from 'ethers';
 export declare const DEFAULT_CONFIRM_TIMEOUT_MS = 180000;
 export interface SendOptions {
     /**
-     * Called with the hash as soon as the transaction is broadcast, before any
-     * wait, and again with the replacement's hash if the wallet re-prices it.
-     * Persist it there: a crash from then on cannot lose it. A throwing callback
-     * does not stop the send, which has already happened.
+     * Called with the hash and nonce as soon as the transaction is broadcast,
+     * before any wait, and again with the replacement's if the wallet re-prices
+     * it. Persist them there: a crash from then on cannot lose them, and the
+     * nonce tells later whether the transaction can still land (once the
+     * sender's confirmed nonce passes it with no receipt, it never will). A
+     * local key's signed raw transaction comes too: re-broadcast while its nonce
+     * is unused, it can only land once, with this hash. A throwing callback does
+     * not stop the send, which has already happened.
      */
-    onSent?: (hash: string) => void | Promise<void>;
+    onSent?: (hash: string, nonce: number, raw?: string) => void | Promise<void>;
     timeoutMs?: number;
     nonce?: number;
     value?: bigint;

package/dist/onchain.js

@@ -21,11 +21,11 @@ export class UnconfirmedTransactionError extends Error {
         this.name = 'UnconfirmedTransactionError';
     }
 }
-async function notify(onSent, hash) {
+async function notify(onSent, hash, nonce, raw) {
     if (!onSent)
         return;
     try {
-        await onSent(hash);
+        await onSent(hash, nonce, raw);
     }
     catch {
         // The transaction is out whatever the callback did; the caller still gets the hash.
@@ -38,14 +38,35 @@ async function notify(onSent, hash) {
  * not be confirmed throws UnconfirmedTransactionError naming the hash.
  */
 export async function sendAndWait(signer, tx, opts = {}) {
-    const sent = await signer.sendTransaction({
+    const request = {
         to: tx.to,
         data: tx.data,
         ...(opts.value !== undefined ? { value: opts.value } : {}),
         ...(opts.nonce !== undefined ? { nonce: opts.nonce } : {}),
         ...(opts.gasLimit !== undefined ? { gasLimit: opts.gasLimit } : {}),
-    });
-    await notify(opts.onSent, sent.hash);
+    };
+    let sent;
+    if (signsLocally(signer)) {
+        // Signed, and its hash and nonce handed to onSent, before it leaves this
+        // process: once the raw transaction is out, a lost reply cannot turn one
+        // that may land into "nothing was sent".
+        const populated = await signer.populateTransaction(request);
+        const raw = await signer.signTransaction(populated);
+        const hash = ethers.keccak256(raw);
+        await notify(opts.onSent, hash, Number(populated.nonce), raw);
+        try {
+            sent = await signer.provider.broadcastTransaction(raw);
+        }
+        catch (err) {
+            const hint = opts.unconfirmedHint ? ` ${opts.unconfirmedHint(hash)}` : '';
+            throw new UnconfirmedTransactionError(hash, `Transaction ${hash} was signed and handed to the node, but no answer came back (${err.message}). It may still land.${hint}`);
+        }
+    }
+    else {
+        // A wallet that signs out of reach (a browser extension) signs and sends in one step.
+        sent = await signer.sendTransaction(request);
+        await notify(opts.onSent, sent.hash, sent.nonce);
+    }
     try {
         const receipt = await sent.wait(1, opts.timeoutMs ?? DEFAULT_CONFIRM_TIMEOUT_MS);
         if (receipt && receipt.status === 0)
@@ -59,7 +80,7 @@ export async function sendAndWait(signer, tx, opts = {}) {
             const replacement = err.replacement;
             if (err.receipt && err.receipt.status === 0)
                 throw new Error(`Transaction ${replacement.hash} reverted, so nothing was paid.`);
-            await notify(opts.onSent, replacement.hash);
+            await notify(opts.onSent, replacement.hash, replacement.nonce);
             return { hash: replacement.hash, nonce: replacement.nonce };
         }
         if (ethers.isError(err, 'CALL_EXCEPTION'))
@@ -70,6 +91,10 @@ export async function sendAndWait(signer, tx, opts = {}) {
         throw new UnconfirmedTransactionError(sent.hash, `Transaction ${sent.hash} was sent but not confirmed (${err.message}).${hint}`);
     }
 }
+/** A signer holding its own key, with a provider: its transactions can be signed, recorded, then broadcast. */
+function signsLocally(signer) {
+    return signer instanceof ethers.BaseWallet && !!signer.provider;
+}
 /**
  * Throw, before anything is sent, unless `signer` is connected to chain
  * `chainId`. A transaction signed on the wrong network can succeed there

package/dist/posting.d.ts

@@ -0,0 +1,63 @@
+import type { Address, AgentCapability, CreateTaskRequest } from './types.js';
+import type { IndexTaskParams, PostTaskParams } from './index.js';
+/** The escrow's deadline bounds (BlindEscrow MIN_DEADLINE / MAX_DEADLINE). */
+export declare const MIN_DURATION_SECONDS = 3600;
+export declare const MAX_DURATION_SECONDS: number;
+/** A brief's key is wrapped to at most this many executors (POST /tasks caps wrappedKeys at 200). */
+export declare const MAX_WRAPPED_KEYS = 200;
+/** A whole number of base units from a string or bigint; throws 400 INVALID_AMOUNT otherwise. */
+export declare function wholeNumber(value: string | bigint, name: string): bigint;
+/** A post with every default filled in and every limit checked. */
+export interface NormalizedPost {
+    instructions: string;
+    amount: bigint;
+    duration: number;
+    privacy: 'private' | 'public';
+    locationZone: string;
+    verificationMode: 'manual' | 'auto' | 'agent';
+    verificationCriteria?: Record<string, unknown>;
+    requiredCapabilities: AgentCapability[];
+    verifierAddress?: Address;
+    targetExecutor?: Address;
+    routingSummary?: string;
+}
+/** POST /a2a/tasks/index takes a routing summary of at most this many characters. */
+export declare const MAX_ROUTING_SUMMARY = 500;
+/**
+ * `params` with its defaults, or the ApiError postTask() has always thrown,
+ * in the same order: INVALID_AMOUNT, AMOUNT_ABOVE_MAX, INVALID_DURATION.
+ */
+export declare function normalizePost(params: PostTaskParams, maxAmountRaw?: bigint | string): NormalizedPost;
+/**
+ * The checks a bulk post adds for fields a caller builds from a file or a
+ * form, where postTask()'s TypeScript types do not reach: a brief with text,
+ * the enums, and the addresses. Throws 400 INVALID_ROW naming the field.
+ */
+export declare function checkRowFields(params: PostTaskParams): void;
+/** An executor as GET /a2a/executors lists it. */
+export interface ExecutorKey {
+    address: string;
+    publicKey?: string;
+}
+/** A brief ready to upload: the bytes, their task hash, and for a private brief its wrapped keys. */
+export interface SealedBrief {
+    blob: Uint8Array;
+    /** 0x + sha256 of `blob`: the commitment createTask escrows against. */
+    taskHash: string;
+    wrappedKeys?: Record<string, string>;
+    /** Hex AES key of a private brief. */
+    aesKey?: string;
+}
+/**
+ * The brief as it is uploaded: plaintext for a public post; otherwise
+ * AES-encrypted, with the key wrapped to each executor that can take it (or
+ * only the target executor). Throws what postTask() has always thrown, with
+ * nothing sent: EXECUTOR_NOT_FOUND, TOO_MANY_EXECUTORS, NO_EXECUTORS.
+ */
+export declare function sealBrief(post: NormalizedPost, executors: readonly ExecutorKey[], postingChain: string): Promise<SealedBrief>;
+/** POST /api/v1/tasks's body for one post (POST /tasks/batch takes the same, less the token). */
+export declare function createTaskBody(post: NormalizedPost, sealed: SealedBrief, token: string, rootHash: string): CreateTaskRequest;
+/** POST /api/v1/a2a/tasks/index's body for one post, with `txHash` still to fill in. */
+export declare function indexParamsFor(post: NormalizedPost, sealed: SealedBrief, rootHash: string): IndexTaskParams;
+/** Whether this post commits a verifier on-chain (createTaskWithVerifier, or a non-zero verifierAgent in createTasks). */
+export declare function commitsVerifier(post: NormalizedPost): boolean;

package/dist/posting.js

@@ -0,0 +1,168 @@
+/**
+ * The pieces of a post that need no network: a post's fields with their
+ * defaults and the escrow's limits, the sealed brief and its task hash, and
+ * the bodies POST /tasks and POST /a2a/tasks/index take. postTask() and
+ * postTasks() share them, so one task and five hundred are checked the same
+ * way, and every row of a bulk post is sealed before anything is sent.
+ */
+import { ethers } from 'ethers';
+import { ApiError } from './apiError.js';
+import { generateAesKey, aesEncrypt, eciesEncrypt, sha256, bytesToHex } from './crypto/index.js';
+/** The escrow's deadline bounds (BlindEscrow MIN_DEADLINE / MAX_DEADLINE). */
+export const MIN_DURATION_SECONDS = 3_600;
+export const MAX_DURATION_SECONDS = 90 * 86_400;
+/** A brief's key is wrapped to at most this many executors (POST /tasks caps wrappedKeys at 200). */
+export const MAX_WRAPPED_KEYS = 200;
+/** A whole number of base units from a string or bigint; throws 400 INVALID_AMOUNT otherwise. */
+export function wholeNumber(value, name) {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'string' && /^\d+$/.test(value))
+        return BigInt(value);
+    throw new ApiError(400, `${name} must be a whole number of the token's smallest unit (USDC has 6 decimals: '2500000' is 2.5 USDC), not ${JSON.stringify(value)}. Nothing was sent.`, undefined, 'INVALID_AMOUNT');
+}
+/** POST /a2a/tasks/index takes a routing summary of at most this many characters. */
+export const MAX_ROUTING_SUMMARY = 500;
+/**
+ * `params` with its defaults, or the ApiError postTask() has always thrown,
+ * in the same order: INVALID_AMOUNT, AMOUNT_ABOVE_MAX, INVALID_DURATION.
+ */
+export function normalizePost(params, maxAmountRaw) {
+    const amount = wholeNumber(params.amountRaw, 'amountRaw');
+    if (amount <= 0n)
+        throw new ApiError(400, 'amountRaw must be above 0. Nothing was sent.', undefined, 'INVALID_AMOUNT');
+    if (maxAmountRaw !== undefined && amount > BigInt(maxAmountRaw)) {
+        throw new ApiError(402, `The escrow of ${amount} is above your limit of ${maxAmountRaw}. Nothing was sent.`, undefined, 'AMOUNT_ABOVE_MAX');
+    }
+    const duration = params.durationSeconds ?? 86_400;
+    if (!Number.isInteger(duration) || duration < MIN_DURATION_SECONDS || duration > MAX_DURATION_SECONDS) {
+        throw new ApiError(400, 'durationSeconds must be a whole number from 3600 (1 hour) to 7776000 (90 days): the escrow refuses anything else. Nothing was sent.', undefined, 'INVALID_DURATION');
+    }
+    const verificationMode = params.verificationMode ?? 'auto';
+    const verificationCriteria = params.verificationCriteria
+        ?? (verificationMode === 'auto' ? { min_length: 10, pass_threshold: 60 } : undefined);
+    // Checked here, before funding: the listing would refuse it after the escrow is paid.
+    const routingSummary = typeof params.routingSummary === 'string' ? params.routingSummary.trim() : undefined;
+    if (routingSummary && routingSummary.length > MAX_ROUTING_SUMMARY) {
+        throw new ApiError(400, `routingSummary is ${routingSummary.length} characters; the task board takes at most ${MAX_ROUTING_SUMMARY}. Nothing was sent.`, undefined, 'INVALID_ROUTING_SUMMARY');
+    }
+    return {
+        instructions: params.instructions,
+        amount,
+        duration,
+        privacy: params.privacy ?? 'private',
+        locationZone: params.locationZone ?? 'global',
+        verificationMode,
+        ...(verificationCriteria ? { verificationCriteria } : {}),
+        requiredCapabilities: params.requiredCapabilities ?? [],
+        ...(params.verifierAddress ? { verifierAddress: params.verifierAddress } : {}),
+        ...(params.targetExecutor ? { targetExecutor: params.targetExecutor } : {}),
+        ...(routingSummary ? { routingSummary } : {}),
+    };
+}
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+/**
+ * The checks a bulk post adds for fields a caller builds from a file or a
+ * form, where postTask()'s TypeScript types do not reach: a brief with text,
+ * the enums, and the addresses. Throws 400 INVALID_ROW naming the field.
+ */
+export function checkRowFields(params) {
+    const bad = (message) => new ApiError(400, `${message} Nothing was sent.`, undefined, 'INVALID_ROW');
+    if (typeof params.instructions !== 'string' || !params.instructions.trim())
+        throw bad('instructions are empty.');
+    if (params.privacy !== undefined && params.privacy !== 'private' && params.privacy !== 'public') {
+        throw bad(`privacy must be 'private' or 'public', not ${JSON.stringify(params.privacy)}.`);
+    }
+    if (params.verificationMode !== undefined && !['manual', 'auto', 'agent'].includes(params.verificationMode)) {
+        throw bad(`verificationMode must be 'auto', 'manual' or 'agent', not ${JSON.stringify(params.verificationMode)}.`);
+    }
+    if (params.targetExecutor !== undefined && !ADDRESS.test(params.targetExecutor)) {
+        throw bad(`targetExecutor must be a 0x wallet address, not ${JSON.stringify(params.targetExecutor)}.`);
+    }
+    if (params.verifierAddress !== undefined && !ADDRESS.test(params.verifierAddress)) {
+        throw bad(`verifierAddress must be a 0x wallet address, not ${JSON.stringify(params.verifierAddress)}.`);
+    }
+    if (params.requiredCapabilities !== undefined && (!Array.isArray(params.requiredCapabilities) || params.requiredCapabilities.some((c) => typeof c !== 'string'))) {
+        throw bad('requiredCapabilities must be a list of capability names.');
+    }
+    if (params.durationSeconds !== undefined && typeof params.durationSeconds !== 'number') {
+        throw bad('durationSeconds must be a number of seconds.');
+    }
+    if (params.routingSummary !== undefined && typeof params.routingSummary !== 'string') {
+        throw bad('routingSummary must be text.');
+    }
+}
+/**
+ * The brief as it is uploaded: plaintext for a public post; otherwise
+ * AES-encrypted, with the key wrapped to each executor that can take it (or
+ * only the target executor). Throws what postTask() has always thrown, with
+ * nothing sent: EXECUTOR_NOT_FOUND, TOO_MANY_EXECUTORS, NO_EXECUTORS.
+ */
+export async function sealBrief(post, executors, postingChain) {
+    const plaintext = new TextEncoder().encode(post.instructions);
+    if (post.privacy === 'public') {
+        return { blob: plaintext, taskHash: `0x${bytesToHex(await sha256(plaintext))}` };
+    }
+    let targets = executors.filter((e) => typeof e.publicKey === 'string' && e.publicKey.length > 0);
+    if (post.targetExecutor) {
+        const want = post.targetExecutor.toLowerCase();
+        targets = targets.filter((e) => e.address.toLowerCase() === want);
+        if (targets.length === 0) {
+            throw new ApiError(404, `${post.targetExecutor} is not a registered executor on ${postingChain} with a public key, so it could not read the brief. Nothing was sent.`, undefined, 'EXECUTOR_NOT_FOUND');
+        }
+    }
+    if (targets.length > MAX_WRAPPED_KEYS) {
+        throw new ApiError(409, `${targets.length} executors match, more than the ${MAX_WRAPPED_KEYS} a brief can be wrapped to. Narrow requiredCapabilities, name a targetExecutor, or post with privacy 'public'. Nothing was sent.`, undefined, 'TOO_MANY_EXECUTORS');
+    }
+    const key = await generateAesKey();
+    const blob = await aesEncrypt(plaintext, key);
+    const wrappedKeys = {};
+    for (const e of targets) {
+        try {
+            wrappedKeys[e.address.toLowerCase()] = bytesToHex(await eciesEncrypt(key, e.publicKey));
+        }
+        catch { /* a malformed public key: that executor can't be wrapped to */ }
+    }
+    if (Object.keys(wrappedKeys).length === 0) {
+        throw new ApiError(409, `No executor on ${postingChain} can decrypt an encrypted brief right now, so no one could take the task. Post with privacy 'public', or wait for executors to register. Nothing was sent.`, undefined, 'NO_EXECUTORS');
+    }
+    return { blob, taskHash: `0x${bytesToHex(await sha256(blob))}`, wrappedKeys, aesKey: bytesToHex(key) };
+}
+/** POST /api/v1/tasks's body for one post (POST /tasks/batch takes the same, less the token). */
+export function createTaskBody(post, sealed, token, rootHash) {
+    return {
+        taskHash: sealed.taskHash,
+        token: token,
+        amount: post.amount.toString(),
+        locationZone: post.locationZone,
+        duration: String(post.duration),
+        targetExecutorType: 'agent',
+        verificationMode: post.verificationMode,
+        ...(post.verificationCriteria ? { verificationCriteria: post.verificationCriteria } : {}),
+        ...(post.verifierAddress ? { verifierAddress: post.verifierAddress } : {}),
+        requiredCapabilities: post.requiredCapabilities,
+        rootHash: rootHash,
+        ...(sealed.wrappedKeys ? { wrappedKeys: sealed.wrappedKeys } : {}),
+    };
+}
+/** POST /api/v1/a2a/tasks/index's body for one post, with `txHash` still to fill in. */
+export function indexParamsFor(post, sealed, rootHash) {
+    return {
+        txHash: '',
+        taskHash: sealed.taskHash,
+        rootHash,
+        ...(sealed.wrappedKeys ? { wrappedKeys: sealed.wrappedKeys } : {}),
+        privacy: post.privacy,
+        ...(post.privacy === 'public' ? { publicBrief: post.instructions.slice(0, 4000) } : {}),
+        verificationMode: post.verificationMode,
+        ...(post.verificationCriteria ? { verificationCriteria: post.verificationCriteria } : {}),
+        ...(post.verifierAddress ? { verifierAddress: post.verifierAddress } : {}),
+        requiredCapabilities: post.requiredCapabilities,
+        ...(post.targetExecutor ? { targetExecutor: post.targetExecutor } : {}),
+        ...(post.routingSummary ? { routingSummary: post.routingSummary } : {}),
+    };
+}
+/** Whether this post commits a verifier on-chain (createTaskWithVerifier, or a non-zero verifierAgent in createTasks). */
+export function commitsVerifier(post) {
+    return post.verificationMode === 'agent' && !!post.verifierAddress && post.verifierAddress.toLowerCase() !== ethers.ZeroAddress;
+}

package/dist/settlementPins.d.ts

@@ -0,0 +1,20 @@
+/**
+ * The escrow and settlement token of each deployment this SDK funds, by chain
+ * id. postTask() and postTasks() approve and fund only these: otherwise both
+ * addresses come from the backend's /health/settlement, and postTasks()
+ * approves a whole run at once, so a backend that named another "escrow"
+ * would be handed that approval (security review). A custom or local
+ * deployment is added through BlindMarketConfig.trustedEscrows.
+ *
+ * Separate from network/presets.ts, which pins the 0G contracts of the
+ * low-level API per SDK version (its testnet entries deliberately point at
+ * an older deployment). These follow contracts/deployments/arc-*.json.
+ */
+export interface SettlementPin {
+    chainId: number;
+    escrow: string;
+    token: string;
+}
+export declare const SETTLEMENT_PINS: readonly SettlementPin[];
+/** Whether `escrow` and `token` on `chainId` are a pinned deployment, or one the caller trusts. */
+export declare function isPinnedSettlement(chainId: number, escrow: string, token: string, trusted?: readonly SettlementPin[]): boolean;

package/dist/settlementPins.js

@@ -0,0 +1,11 @@
+export const SETTLEMENT_PINS = Object.freeze([
+    // Arc mainnet
+    { chainId: 5042, escrow: '0xd2B819B57a9568Cb6bFc98C687F9a851EC8330C4', token: '0x3600000000000000000000000000000000000000' },
+    // Arc Testnet
+    { chainId: 5042002, escrow: '0xaBf70843E0380F1e749d2b85C30dD6820Ff5C731', token: '0x3600000000000000000000000000000000000000' },
+]);
+/** Whether `escrow` and `token` on `chainId` are a pinned deployment, or one the caller trusts. */
+export function isPinnedSettlement(chainId, escrow, token, trusted = []) {
+    const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+    return [...SETTLEMENT_PINS, ...trusted].some((p) => p.chainId === chainId && same(p.escrow, escrow) && same(p.token, token));
+}

package/dist/tools/helpers.js

@@ -24,7 +24,7 @@ export function kit(name, description, all, names) {
 }
 export function createBlindMarketTools(bb) {
     const all = [
-        tool(bb, 'list_open_tasks', 'List open tasks available for assignment', {}, async () => {
+        tool(bb, 'list_open_tasks', 'List open tasks from the legacy 0G TaskRegistry (numeric ids on the 0G escrow). Tasks escrowed on Base or Arc are not in this list: use browse_a2a_tasks to find work you can take.', {}, async () => {
             return bb.listTasks();
         }),
         tool(bb, 'get_task', 'Get full task details by ID', { taskId: str('Numeric or 0x task ID') }, async (a) => {

package/dist/types.d.ts

@@ -181,6 +181,19 @@ export interface A2APublicTaskMeta {
     privacy?: 'public';
     hasEncryptedBrief?: boolean;
     rootHash?: string;
+    /**
+     * The escrowed reward, recorded by the backend from the verified TaskCreated
+     * event at /tasks/index: `amount` is a whole number of the unit's base units
+     * (USDC: 6 decimals, so '1000000' is 1 USDC). Absent on tasks indexed by a
+     * backend older than the field. WorkerRuntime compares it with `minReward`.
+     */
+    reward?: {
+        amount: string;
+        unit: {
+            symbol: 'USDC' | '0G';
+            decimals: 6 | 18;
+        };
+    };
     [key: string]: unknown;
 }
 /** One entry of `GET /api/v1/a2a/tasks` (and /tasks/posted, /executions). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blindmarket/sdk",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "BlindMarket SDK — deploy agents, assign workers, verify evidence",
   "author": "BlindMarket Team",
   "license": "MIT",