@blindmarket/sdk 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ethers } from 'ethers';
 import { ApiError } from './apiError.js';
+import { type SettlementPin } from './settlementPins.js';
 import type { Address, Hex, RootHash, HealthStatus, PlatformStats, OpenTask, TaskDetail, CreateTaskTx, ExecutorProfile, RegisterExecutorInput, DeployedAgentInfo, AgentWalletInfo, ReputationInfo, LeaderboardEntry, StorageUploadResult, Message, AgentSearchResult, TaskTemplate, VerifyTaskInput, A2ATaskEntry, AgentCapability, CreateAgentParams, CreateAgentResult, CreateTaskRequest } from './types.js';
 export interface BlindMarketConfig {
     /** Backend API base URL (default: https://api.blindmarket.xyz) */
@@ -13,6 +14,14 @@ export interface BlindMarketConfig {
      * never take a key as an argument. Stays in-process; never sent to the backend.
      */
     executor?: DeliverSigner;
+    /**
+     * Escrows postTask() and postTasks() may fund besides the known
+     * deployments (SETTLEMENT_PINS: Arc mainnet and Arc Testnet), for a custom
+     * or local deployment. Each names its chain id, escrow and settlement
+     * token; the backend's /health/settlement must name exactly one of them, or
+     * nothing is approved or funded (ESCROW_NOT_PINNED).
+     */
+    trustedEscrows?: SettlementPin[];
 }
 export interface DeployAgentParams {
     name: string;
@@ -141,6 +150,12 @@ export interface PostTaskParams {
     targetExecutor?: Address;
     /** Default 'global'. */
     locationZone?: string;
+    /**
+     * A public one-liner shown on the task board, at most 500 characters. A
+     * private task's brief is sealed, so this is what the board says it is
+     * about: keep secrets out of it.
+     */
+    routingSummary?: string;
 }
 export interface PostTaskOptions {
     /**
@@ -162,6 +177,8 @@ export interface PostTaskOptions {
      */
     onFunded?: (funding: {
         txHash: string;
+        nonce: number;
+        raw?: string;
         taskHash: string;
         indexParams: IndexTaskParams;
     }) => void | Promise<void>;
@@ -200,6 +217,168 @@ export interface IndexTaskParams {
     verifierAddress?: Address;
     requiredCapabilities?: AgentCapability[];
     targetExecutor?: Address;
+    routingSummary?: string;
+}
+export interface PostTasksOptions {
+    /** As postTask(): signs on the posting chain instead of the configured executor, and must be the API key's own wallet. */
+    signer?: ethers.Signer;
+    /**
+     * The most postTasks() will lock in escrow across every row, in the
+     * token's smallest unit. Refused with AMOUNT_ABOVE_MAX before anything is sent.
+     */
+    maxTotalRaw?: bigint | string;
+    /**
+     * Tasks per transaction on an escrow that has createTasks (SettlementChainInfo.batchCreate).
+     * Default 20, at most the chain's maxBatch and 50. On an escrow without
+     * it every task is its own transaction and this is ignored.
+     */
+    chunkSize?: number;
+    /** Called as each row settles: posted, unlisted, failed or skipped. A throwing callback does not stop the run. */
+    onProgress?: (progress: {
+        done: number;
+        total: number;
+        result: PostTasksRowResult;
+    }) => void | Promise<void>;
+    /**
+     * Called the moment a funding transaction is broadcast, once for every row
+     * it funds. Persist `indexParams`: if this process dies before the row is
+     * listed, indexTask(indexParams) lists it without funding it again, or
+     * indexTasks() for rows whose `batch` is true, which share one transaction
+     * (the single index route refuses a receipt that funded several tasks).
+     */
+    onFunded?: (funding: {
+        index: number;
+        txHash: string;
+        nonce: number;
+        raw?: string;
+        taskHash: string;
+        batch: boolean;
+        indexParams: IndexTaskParams;
+    }) => void | Promise<void>;
+    /** How long to wait for each transaction to confirm. Default 180000 ms. */
+    confirmTimeoutMs?: number;
+    /**
+     * Stops the run before the next row, or the next transaction of rows; a
+     * transaction already sent is always seen through to its listing. Rows not
+     * started come back 'skipped'.
+     */
+    signal?: AbortSignal;
+    /**
+     * Backoff for a rate limit (429), a 5xx or a network error on a read, an
+     * upload, a build or a listing: `attempts` tries in all (default 5), the
+     * wait doubling from `baseDelayMs` (default 2000). A funding transaction is
+     * never sent twice.
+     */
+    retry?: {
+        attempts?: number;
+        baseDelayMs?: number;
+    };
+}
+/** A row that cannot be posted as it is, from postTasks()' checks before anything is sent (ApiError INVALID_ROWS, `body.errors`). */
+export interface PostTasksRowError {
+    /** The row's position in the array passed to postTasks(). */
+    index: number;
+    code: string;
+    message: string;
+}
+/** What happened to one row of postTasks(), by its position in the input. */
+export type PostTasksRowResult = 
+/** Funded and listed. */
+{
+    index: number;
+    status: 'posted';
+    task: PostedTask;
+}
+/**
+ * Funded (or sent and maybe funded, with code UNCONFIRMED) but not listed.
+ * Do not post it again: list it with indexTask(indexParams), or with
+ * indexTasks() when `batch` is true, or cancel it for a refund.
+ */
+ | {
+    index: number;
+    status: 'unlisted';
+    taskHash: string;
+    txHash: string;
+    batch: boolean;
+    indexParams: IndexTaskParams;
+    aesKey?: string;
+    error: {
+        code?: string;
+        message: string;
+    };
+}
+/** Nothing was funded for this row. */
+ | {
+    index: number;
+    status: 'failed';
+    error: {
+        code?: string;
+        message: string;
+    };
+}
+/** Not started: the run was aborted, or stopped at an earlier row. */
+ | {
+    index: number;
+    status: 'skipped';
+    reason: string;
+};
+export interface PostTasksResult {
+    chain: string;
+    chainId: number;
+    /** 'batch': createTasks, several tasks per transaction. 'single': one createTask per task. */
+    mode: 'batch' | 'single';
+    /** One per input row, in input order. */
+    results: PostTasksRowResult[];
+    posted: number;
+    unlisted: number;
+    failed: number;
+    skipped: number;
+    /**
+     * Why the run stopped before the last row, when it did: an on-chain or
+     * listing failure (so no further escrow is funded behind it), a backend
+     * that built the wrong transaction, one that stayed unreachable, or the abort signal.
+     */
+    stopped?: {
+        index: number;
+        code?: string;
+        message: string;
+    };
+}
+/** POST /api/v1/tasks/batch: several posts built into one createTasks transaction. */
+export interface CreateTasksRequest {
+    token: Address;
+    tasks: Array<Omit<CreateTaskRequest, 'token'>>;
+}
+export interface CreateTasksTx {
+    unsignedTx: {
+        to: Address;
+        data: Hex;
+        value?: string;
+        from?: Address;
+    };
+    chain?: string;
+    chainId?: number;
+    /** The task hashes the transaction escrows, in order. */
+    taskHashes?: string[];
+}
+/** POST /api/v1/a2a/tasks/index-batch: list the tasks one transaction funded. */
+export interface IndexTasksParams {
+    txHash: string;
+    isUserOp?: boolean;
+    tasks: Array<Omit<IndexTaskParams, 'txHash'>>;
+}
+export interface IndexTasksResult {
+    results: Array<{
+        taskHash: string;
+        onChainTaskId?: string;
+        indexed: true;
+    } | {
+        taskHash: string;
+        error: {
+            code?: string;
+            message: string;
+        };
+    }>;
 }
 /** A refund the client signed and sent: cancelAndRefund() or reclaimAfterTimeout(). */
 export interface RefundResult {
@@ -239,6 +418,15 @@ export interface SettlementChainInfo {
     relayChain?: string | null;
     gasSymbol?: string;
     postable?: boolean;
+    /**
+     * Whether this chain's escrow has createTasks (several tasks in one
+     * transaction), and how many one call takes. Absent from older backends,
+     * which is the same as unsupported.
+     */
+    batchCreate?: {
+        supported: boolean;
+        maxBatch: number;
+    };
 }
 /** Per-chain RPC URLs for signing `submitEvidence` — a task is escrowed on exactly one chain. */
 export interface DeliverSigner {
@@ -271,6 +459,7 @@ export declare class BlindMarket {
     private apiBase;
     private apiKey;
     private executor?;
+    private trustedEscrows;
     constructor(config: BlindMarketConfig);
     /** True when an executor signer was configured (see BlindMarketConfig.executor). */
     get canSign(): boolean;
@@ -300,6 +489,12 @@ export declare class BlindMarket {
      * generateText({ model, tools: tools(bb).vercel });
      * ```
      */
+    /**
+     * `timeoutMs` gives up on a request that has not answered (ApiError
+     * TIMEOUT). `strictBody` turns a reply that is not JSON (a gateway's error
+     * page, such as Cloudflare's 524) into an ApiError carrying its HTTP status,
+     * instead of the parser's SyntaxError.
+     */
     private req;
     /** Backend liveness check. */
     health(): Promise<HealthStatus>;
@@ -396,6 +591,109 @@ export declare class BlindMarket {
      * );
      */
     postTask(params: PostTaskParams, opts?: PostTaskOptions): Promise<PostedTask>;
+    /**
+     * Post many tasks, from the API key's own wallet: postTask() for a list, in
+     * as few transactions as the posting chain's escrow allows.
+     *
+     * Every row is checked and its brief sealed before anything is uploaded or
+     * sent: a row the escrow or the backend would refuse throws 400
+     * INVALID_ROWS listing every such row (`err.body.errors`), with nothing
+     * sent. The wallet must hold the total, and the escrow is approved for it
+     * once, just before the first funding transaction.
+     *
+     * On an escrow with createTasks (SettlementChainInfo.batchCreate) up to
+     * `chunkSize` rows share one transaction and one listing call; otherwise
+     * each row is its own createTask, as postTask() sends it. The same checks
+     * guard every transaction: the backend's build must be exactly these tasks,
+     * for this escrow and chain, before a key signs it.
+     *
+     * A row the backend refuses before funding fails alone and the run goes on.
+     * A funding transaction that reverts or cannot be confirmed, a listing that
+     * fails, or a backend that builds the wrong transaction or stays
+     * unreachable stops the run there (`result.stopped`), so no further escrow
+     * is funded behind a problem. Nothing is ever funded twice: a funded row
+     * that is not listed comes back 'unlisted' with its `indexParams`.
+     *
+     * @example
+     * const res = await bb.postTasks(rows, {
+     *   onFunded: ({ taskHash, indexParams }) => save(taskHash, indexParams),
+     *   onProgress: ({ done, total }) => console.log(`${done}/${total}`),
+     * });
+     */
+    postTasks(rows: PostTaskParams[], opts?: PostTasksOptions): Promise<PostTasksResult>;
+    /**
+     * Build and list several posts at once (POST /api/v1/tasks/batch): one
+     * unsigned createTasks transaction for the posting chain's escrow. Only an
+     * escrow with createTasks builds it (409 BATCH_UNSUPPORTED otherwise);
+     * postTasks() calls it, and checks the transaction before signing.
+     */
+    createTasks(params: CreateTasksRequest): Promise<CreateTasksTx>;
+    /**
+     * List every task one funding transaction created
+     * (POST /api/v1/a2a/tasks/index-batch). It works for a transaction that
+     * funded one task too. Each task comes back listed, or with its own error;
+     * a task the receipt does not hold is NOT_IN_RECEIPT. postTasks() calls it;
+     * call it yourself to finish rows it returned 'unlisted' with `batch` true.
+     */
+    indexTasks(params: IndexTasksParams): Promise<IndexTasksResult>;
+    /**
+     * Upload several blobs to 0G Storage in one call
+     * (POST /api/v1/storage/upload-batch). Each is base64, as uploadBlob()
+     * takes it; the results come back in the same order. All or nothing.
+     */
+    uploadBlobs(data: string[]): Promise<Array<{
+        rootHash: string;
+        txHash?: string;
+    }>>;
+    /** The posting chain, its escrow and token, and a signer checked to be the API key's own wallet on that chain. */
+    private postingContext;
+    /** Throws 402 INSUFFICIENT_BALANCE, with nothing sent, when the wallet holds less than `amount` of an ERC-20 settlement token. */
+    private assertCovers;
+    /** The executors on the posting chain a private brief can be wrapped to. */
+    private postingExecutors;
+    /**
+     * The backend's createTask, checked to be exactly this post before a key
+     * signs it: the chain and escrow checked above, the task hash, the token,
+     * the amount, the zone and the duration (a verifier commits through
+     * createTaskWithVerifier). Only its to and data are signed; the value is
+     * the amount computed here.
+     */
+    private checkedCreateCall;
+    /** The backend's createTasks, checked to be exactly these posts, in this order, for this token, escrow and chain. */
+    private checkedCreateTasksCall;
+    private postedTask;
+    /**
+     * The escrow's ERC-20 allowance for every row still to fund, approved once,
+     * right before the first funding transaction (after that transaction's
+     * build has been checked, as postTask() approves).
+     */
+    private approveRemaining;
+    /** Every row a transaction funds, told its hash (again with a replacement's hash if the wallet re-priced it). */
+    private notifyFunded;
+    /** One row as its own createTask, the way postTask() posts it. */
+    private postRow;
+    /** Several rows in one createTasks transaction, listed with one call. */
+    private postChunk;
+    /**
+     * Store briefs (base64) and return their root hashes, in order. Batched
+     * (upload-batch), they go UPLOAD_GROUP to a request, one request after the
+     * other; a group that fails transiently (isTransientUpload) is sent again
+     * one brief per request, each with the backoff, and a brief already stored
+     * comes back at once. Unbatched, each brief is one /storage/upload request
+     * with the backoff. A refusal (a 400) or an answer that does not add up
+     * fails at once.
+     */
+    private uploadBriefs;
+    /** One /storage/upload-batch request, checked to answer one root hash per brief. */
+    private uploadBatchRequest;
+    /** One /storage/upload request, as postTask() stores a brief. */
+    private uploadOneRequest;
+    /**
+     * `fn`, asked again after a rate limit, a 5xx or a network error (and, for
+     * a listing, while the backend's RPC has not seen the receipt), or after
+     * what `retryable` says is worth another try.
+     */
+    private retrying;
     /**
      * List a funded task on the market (`POST /api/v1/a2a/tasks/index`), from
      * its funding transaction. Safe to call again for the same task: the
@@ -867,6 +1165,8 @@ export declare class BlindMarket {
 }
 export { ethers };
 export { ApiError };
+export { SETTLEMENT_PINS, isPinnedSettlement } from './settlementPins.js';
+export type { SettlementPin } from './settlementPins.js';
 export { tools, createBlindMarketTools, createTaskTools, createAgentManagementTools, createA2ATools, toLangChainTools, toVercelTools, toOpenAITools, toClaudeTools, } from './tools/index.js';
 export type { Tool, ToolKit, ToolDefinition } from './tools/types.js';
 export type { BlindMarketTools } from './tools/index.js';