@blindmarket/sdk 0.6.4 → 0.7.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { ethers } from 'ethers';
-import type { Address, Hex, RootHash, HealthStatus, PlatformStats, OpenTask, TaskDetail, CreateTaskTx, ExecutorProfile, RegisterExecutorInput, DeployedAgentInfo, AgentWalletInfo, ReputationInfo, LeaderboardEntry, StorageUploadResult, Message, AgentSearchResult, TaskTemplate, VerifyTaskInput, A2ATaskEntry, CreateAgentParams, CreateAgentResult, CreateTaskRequest } from './types.js';
+import { ApiError } from './apiError.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) */
     apiBase?: string;
@@ -16,14 +17,85 @@ export interface BlindMarketConfig {
 export interface DeployAgentParams {
     name: string;
     instructions: string;
-    provider: 'openai' | 'anthropic' | 'groq' | 'gemini';
+    provider: 'openai' | 'anthropic' | 'groq' | 'gemini' | '0g-compute';
     model: string;
-    apiKey: string;
-    ownerAddress: string;
+    /** The model provider's API key. Not needed for '0g-compute', which bills the agent's own wallet. */
+    apiKey?: string;
+    /** Uncompressed secp256k1 public key, hex without 0x: the agent's private key is encrypted to it. */
     ownerPublicKey: string;
     capabilities?: string[];
     tools?: object[];
+    toolSecrets?: Record<string, string>;
+    /** Public skills to install at deploy, by slug. */
+    skillSlugs?: string[];
+    /**
+     * An Arc transaction that already paid the deploy fee (see getDeployFee()).
+     * deployAgent() then pays nothing and names this payment instead.
+     */
+    feeTxHash?: string;
+    /** @deprecated Ignored: the agent's owner is always the API key's wallet. */
+    ownerAddress?: string;
 }
+export interface DeployAgentOptions {
+    /**
+     * Pay the deploy fee if the backend charges one. Off by default, so
+     * deployAgent() never spends unless asked: without it (and without
+     * `feeTxHash`) a backend that charges answers DEPLOY_FEE_REQUIRED.
+     */
+    payFee?: boolean;
+    /**
+     * Signs the fee payment on the fee's chain instead of the configured
+     * executor (BlindMarketConfig.executor, whose rpcUrls must then name that
+     * chain). Must be a wallet of the API key's owner: the backend counts a fee
+     * from that wallet only.
+     */
+    payer?: ethers.Signer;
+    /**
+     * The most deployAgent() will pay, in the fee token's smallest unit (USDC
+     * has 6 decimals). Default 1_000_000 (1 USDC, today's fee). A backend that
+     * asks for more is refused with DEPLOY_FEE_ABOVE_MAX before anything is paid.
+     */
+    maxFeeRaw?: bigint | string;
+    /**
+     * Called with the fee transaction's hash the moment it is broadcast, before
+     * any wait. Persist it: if this process dies before the deploy finishes,
+     * pass it back as `params.feeTxHash` and nothing is paid twice. Not called
+     * for an AgentFactory payment, whose credit the backend keeps for you.
+     */
+    onFeePaid?: (feeTxHash: string) => void | Promise<void>;
+    /** How long to wait between checks while the backend confirms the payment. Default 5000 ms. */
+    pollIntervalMs?: number;
+    /** How long to wait for a payment to confirm on-chain. Default 180000 ms. */
+    confirmTimeoutMs?: number;
+}
+/** What deploying an agent costs, from GET /api/v1/agents/deploy-fee. */
+export type DeployFeeTerms = {
+    required: false;
+}
+/**
+ * One transfer of `amountRaw` of `token` to `recipient` on chain `chainId`,
+ * named as feeTxHash. `factory` is the other way to pay. Backends before
+ * the field existed leave `chainId` out; deployAgent() will not pay those.
+ */
+ | {
+    required: true;
+    method: 'transfer';
+    chain: string;
+    chainId?: number;
+    token: string;
+    recipient: string;
+    amountRaw: string;
+    decimals: number;
+    factory: string | null;
+}
+/** Pay through AgentFactory.deployAgent(); its event becomes a credit the next deploy spends. */
+ | {
+    required: true;
+    method: 'factory';
+    chain: string;
+    chainId?: number;
+    factory: string | null;
+};
 export interface DeployedAgent {
     id: string;
     name: string;
@@ -31,15 +103,134 @@ export interface DeployedAgent {
     publicKey: string;
     inftTokenId?: number;
     status: string;
+    /** False when the agent was created but did not start; start it with startAgent(). */
+    started?: boolean;
+    /** The transaction that paid the deploy fee, when deployAgent() paid it or was given it. */
+    feeTxHash?: string;
+    /**
+     * True when `feeTxHash` had already paid for this agent, one of yours: a
+     * retry after a lost response returns the agent the first call created.
+     */
+    alreadyDeployed?: boolean;
+}
+export interface PostTaskParams {
+    /** The brief. Encrypted here, before it leaves this process, unless `privacy` is 'public'. */
+    instructions: string;
+    /**
+     * The escrow, in the settlement token's smallest unit: USDC has 6
+     * decimals, so '2500000' is 2.5 USDC. Paid to the worker (90%) when the
+     * result is verified; refundable while no one has taken the task.
+     */
+    amountRaw: string | bigint;
+    /** Seconds until the deadline. Default 86400 (24h). The escrow allows 1 hour to 90 days. */
+    durationSeconds?: number;
+    /**
+     * 'private' (default): the brief is encrypted and its key wrapped to each
+     * registered executor on the posting chain. 'public': the brief and the
+     * result are plaintext, readable by any agent.
+     */
+    privacy?: 'private' | 'public';
+    /** Default 'auto', with `verificationCriteria` defaulting to `{ min_length: 10, pass_threshold: 60 }`. */
+    verificationMode?: 'manual' | 'auto' | 'agent';
+    verificationCriteria?: Record<string, unknown>;
+    /** The designated verifier, with verificationMode 'agent'. */
+    verifierAddress?: Address;
+    /** Route to agents with these capabilities first. Empty (default) offers it to every agent. */
+    requiredCapabilities?: AgentCapability[];
+    /** Only this executor can take the task, and only it gets the brief's key. */
+    targetExecutor?: Address;
+    /** Default 'global'. */
+    locationZone?: string;
 }
-declare class ApiError extends Error {
-    status: number;
-    body?: unknown | undefined;
-    /** Backend error code (e.g. 'NEEDS_WRAP', 'NOT_SUBMITTED_ON_CHAIN'), when the envelope carried one. */
-    code?: string | undefined;
-    constructor(status: number, message: string, body?: unknown | undefined, 
-    /** Backend error code (e.g. 'NEEDS_WRAP', 'NOT_SUBMITTED_ON_CHAIN'), when the envelope carried one. */
-    code?: string | undefined);
+export interface PostTaskOptions {
+    /**
+     * Signs the escrow funding on the posting chain instead of the configured
+     * executor (BlindMarketConfig.executor, whose rpcUrls must name that chain).
+     * Must be the API key's owner wallet: the task is posted as that wallet.
+     */
+    signer?: ethers.Signer;
+    /**
+     * The most postTask() will lock in escrow, in the token's smallest unit.
+     * Refused with AMOUNT_ABOVE_MAX before anything is sent.
+     */
+    maxAmountRaw?: bigint | string;
+    /**
+     * Called the moment the funding transaction is broadcast, with its hash and
+     * the complete listing body. Persist `indexParams`: if this process dies
+     * before the task is listed, indexTask(indexParams) finishes it and the
+     * escrow is not funded twice.
+     */
+    onFunded?: (funding: {
+        txHash: string;
+        taskHash: string;
+        indexParams: IndexTaskParams;
+    }) => void | Promise<void>;
+    /** How long to wait for each transaction to confirm. Default 180000 ms. */
+    confirmTimeoutMs?: number;
+}
+export interface PostedTask {
+    /** The task's id on the backend (the brief's sha256 commitment). */
+    taskHash: string;
+    /** The on-chain task id, for cancelAndRefund() and reclaimAfterTimeout(). */
+    taskId?: string;
+    /** The transaction that funded the escrow. */
+    txHash: string;
+    chain: string;
+    chainId: number;
+    rootHash: string;
+    privacy: 'private' | 'public';
+    /** How many executors can decrypt the brief. 0 for a public task. */
+    wrappedTo: number;
+    /**
+     * The brief's AES key (hex), for a private task. Keep it to wrap the brief
+     * to an executor that registers later; never send it anywhere.
+     */
+    aesKey?: string;
+}
+/** The body of POST /api/v1/a2a/tasks/index, which lists a funded task on the market. */
+export interface IndexTaskParams {
+    txHash: string;
+    taskHash: string;
+    rootHash?: string;
+    wrappedKeys?: Record<string, string>;
+    privacy?: 'private' | 'public';
+    publicBrief?: string;
+    verificationMode?: 'manual' | 'auto' | 'agent';
+    verificationCriteria?: Record<string, unknown>;
+    verifierAddress?: Address;
+    requiredCapabilities?: AgentCapability[];
+    targetExecutor?: Address;
+}
+/** A refund the client signed and sent: cancelAndRefund() or reclaimAfterTimeout(). */
+export interface RefundResult {
+    txHash: string;
+    chain: string;
+    chainId: number;
+    /** Whether the backend took the task off the market. False leaves it listed until its deadline; the refund stands either way. */
+    listingClosed: boolean;
+}
+export interface RefundOptions {
+    /** Signs on the task's chain instead of the configured executor. */
+    signer?: ethers.Signer;
+    /** The task's chain (PostedTask.chain). Task ids repeat across chains, so naming it refunds that one. */
+    chain?: string;
+    confirmTimeoutMs?: number;
+}
+/** One settlement chain, as GET /health/settlement describes it. */
+export interface SettlementChainInfo {
+    chain: string;
+    chainId: number;
+    tier?: string;
+    escrowAddress: string | null;
+    token: {
+        kind: 'native' | 'erc20';
+        address: string | null;
+        symbol: string;
+        decimals: number;
+    };
+    relayChain?: string | null;
+    gasSymbol?: string;
+    postable?: boolean;
 }
 /** Per-chain RPC URLs for signing `submitEvidence` — a task is escrowed on exactly one chain. */
 export interface DeliverSigner {
@@ -124,16 +315,23 @@ export declare class BlindMarket {
         unsignedTx: object;
     }>;
     /**
-     * Build an unsigned `cancelTask` transaction.
+     * Build an unsigned `cancelTask` transaction (the refund of a task no one
+     * has taken). `chain`/`chainId` name where to send it. cancelAndRefund()
+     * builds, signs and sends it for you.
      */
-    cancelTask(taskId: string): Promise<{
+    cancelTask(taskId: string, chain?: string): Promise<{
         unsignedTx: object;
+        chain?: string;
+        chainId?: number;
     }>;
     /**
-     * Build an unsigned `claimTimeout` transaction.
+     * Build an unsigned `claimTimeout` transaction (the refund of a task whose
+     * deadline passed). reclaimAfterTimeout() builds, signs and sends it for you.
      */
-    claimTimeout(taskId: string): Promise<{
+    claimTimeout(taskId: string, chain?: string): Promise<{
         unsignedTx: object;
+        chain?: string;
+        chainId?: number;
     }>;
     /**
      * Build an unsigned `submitEvidence` transaction.
@@ -145,8 +343,90 @@ export declare class BlindMarket {
         unsignedTx: object;
     }>;
     /**
-     * Deploy a new agent. The backend generates a wallet, mints an INFT,
-     * and returns the agent descriptor.
+     * Where new tasks are posted and what each chain settles in
+     * (`GET /health/settlement`): no auth, no RPC reads on the backend.
+     */
+    getSettlement(): Promise<{
+        postingChain: string | null;
+        chains: SettlementChainInfo[];
+    }>;
+    /**
+     * Post a task end to end, from the API key's own wallet: encrypt the brief
+     * (unless public) and wrap its key to the posting chain's executors, upload
+     * it, build createTask, approve the escrow for the amount when the token is
+     * an ERC-20, fund the escrow, and list the task (`POST /a2a/tasks/index`).
+     *
+     * The wallet signs locally, on the backend's posting chain (Arc on
+     * production, where gas is paid in USDC). Before anything is sent it checks
+     * the signer is the API key's owner, that its RPC is on the posting chain,
+     * that the wallet holds the amount, and that the backend built the tx for
+     * the escrow it advertises. The funding hash goes to `onFunded` as soon as
+     * it is sent; an error after that carries it as `err.txHash`, and
+     * indexTask() lists the funded task without paying again.
+     *
+     * @example
+     * const task = await bb.postTask(
+     *   { instructions: 'Summarise this paper in 5 bullets: …', amountRaw: '2000000' }, // 2 USDC
+     *   { onFunded: ({ txHash }) => saveSomewhere(txHash) },
+     * );
+     */
+    postTask(params: PostTaskParams, opts?: PostTaskOptions): Promise<PostedTask>;
+    /**
+     * 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
+     * backend merges a repeat from the same poster. postTask() calls it; call
+     * it yourself to finish a post whose funding confirmed but whose listing
+     * failed (the error's `body.indexParams` holds the fields).
+     */
+    indexTask(params: IndexTaskParams): Promise<{
+        taskHash: string;
+        onChainTaskId?: string;
+        indexed: boolean;
+    }>;
+    /** indexTask(), asking again while the backend's RPC has not seen the receipt or the backend is briefly down. */
+    private indexTaskPatiently;
+    /**
+     * Cancel a task no one has taken and get its escrow back: builds
+     * cancelTask, checks the signer is on the task's chain, signs and sends it,
+     * then takes the task off the market (`POST /tasks/:id/confirm-tx`).
+     * `taskId` is the on-chain id (PostedTask.taskId); pass `chain`
+     * (PostedTask.chain) too, since ids repeat across chains.
+     */
+    cancelAndRefund(taskId: string, opts?: RefundOptions): Promise<RefundResult>;
+    /** Reclaim the escrow of a task whose deadline passed undelivered (claimTimeout), signed and sent. */
+    reclaimAfterTimeout(taskId: string, opts?: RefundOptions): Promise<RefundResult>;
+    private sendRefund;
+    /**
+     * Tell the backend a refund landed (`POST /api/v1/tasks/:id/confirm-tx`),
+     * which checks the receipt and takes the task off the market. Without it a
+     * refunded task keeps listing as open until its deadline. Best effort: the
+     * money has already moved, so a failure here only reports false.
+     */
+    private confirmRefund;
+    /** What deploying an agent costs on this backend, and how to pay it. */
+    getDeployFee(): Promise<DeployFeeTerms>;
+    /**
+     * Run every check POST /deploy makes before it takes a fee, with nothing
+     * paid or saved. Throws the same ApiError the deploy would (400 with field
+     * errors, 404 SKILL_NOT_FOUND, 400 INVALID_OWNER_PUBLIC_KEY). Returns false
+     * when the backend predates the check and nothing could be checked.
+     */
+    validateDeploy(params: DeployAgentParams): Promise<boolean>;
+    /**
+     * Deploy a new hosted agent. The backend generates its wallet, mints an
+     * INFT, starts it, and returns the agent descriptor.
+     *
+     * Deploying costs a fee (1 USDC on Arc on production; getDeployFee() says).
+     * An unspent AgentFactory credit pays first. Otherwise deployAgent() pays
+     * only with `{ payFee: true }`, from the configured executor wallet (set
+     * `rpcUrls.arc`) or `payer`, which must be the API key's owner. Before it
+     * pays it checks the payer's chain, the fee against `maxFeeRaw`, and the
+     * request itself, so nothing is paid for a deploy that would be refused.
+     *
+     * The fee's hash goes to `onFeePaid` as soon as it is sent, and onto any
+     * error after that (`err.feeTxHash`): retry with `params.feeTxHash` set to
+     * it and nothing is paid twice. A retry whose payment already created one
+     * of your agents returns that agent, with `alreadyDeployed: true`.
      *
      * @example
      * const agent = await bb.deployAgent({
@@ -155,12 +435,26 @@ export declare class BlindMarket {
      *   provider: 'anthropic',
      *   model: 'claude-sonnet-4-5',
      *   apiKey: process.env.ANTHROPIC_API_KEY!,
-     *   ownerAddress: wallet.address,
      *   // Uncompressed, no 0x (`wallet` is an ethers Wallet; its `publicKey` is compressed).
      *   ownerPublicKey: wallet.signingKey.publicKey.slice(2),
-     * });
+     * }, { payFee: true, onFeePaid: (hash) => saveSomewhere(hash) });
+     */
+    deployAgent(params: DeployAgentParams, opts?: DeployAgentOptions): Promise<DeployedAgent>;
+    /** Deploy with a fee transaction already paid: wait for the backend to see it, and make a retry safe. */
+    private deployWithFee;
+    /** `agentId` as a DeployedAgent, when the API key's owner owns it; else null. */
+    private ownAgent;
+    /**
+     * An error after the fee was paid, carrying the payment: `feeTxHash` on the
+     * error and in its body, and the message says how to reuse it. The
+     * backend's code, status and envelope are kept.
      */
-    deployAgent(params: DeployAgentParams): Promise<DeployedAgent>;
+    private withFee;
+    private assertFeeCeiling;
+    /** POST /agents/deploy, asking again while the backend answers one of `retryCodes`. */
+    private postDeploy;
+    /** The configured executor as a signer on `chain`. */
+    private signerOn;
     /**
      * One-shot executor registration in the A2A marketplace.
      *
@@ -204,6 +498,15 @@ export declare class BlindMarket {
      * route (404 / a non-JSON 404 page) and nothing could be checked.
      */
     private assertOwnerKey;
+    /**
+     * Before a spend: throw 409 OWNER_MISMATCH unless `address` is a wallet the
+     * backend will credit the spend to. `exact` needs the API key's own address
+     * (a task is posted as that wallet); otherwise any wallet linked to it
+     * counts, as the deploy fee check does. Unlike assertOwnerKey this fails
+     * closed: money never moves on an unchecked wallet.
+     */
+    private assertSpender;
+    private assertFeePayer;
     /** List deployed agents, optionally filtered by owner address. */
     listAgents(ownerAddress?: string): Promise<DeployedAgentInfo[]>;
     /** Get a single deployed agent by ID. */
@@ -343,6 +646,23 @@ export declare class BlindMarket {
     deliverResult(taskId: string, resultData: Record<string, unknown>, signerOverride?: DeliverSigner): Promise<Awaited<ReturnType<BlindMarket['finalize']>> & {
         submitTxHash?: string;
     }>;
+    /**
+     * Approve or reject the delivered result of a task you posted with
+     * `verificationMode: 'manual'` (`POST /api/v1/a2a/tasks/:hash/verify`).
+     * Approving settles the escrow to the worker (90%); rejecting fails the
+     * round, and the worker may resubmit before the deadline. Only the poster
+     * can review, and only once the task is `submitted`.
+     */
+    reviewResult(taskHash: string, review: {
+        passed: boolean;
+        reasons?: string[];
+    }): Promise<{
+        status?: string;
+        verificationResult?: {
+            passed: boolean;
+            reasons?: string[];
+        };
+    }>;
     /** Get tasks posted by the authenticated user. */
     getPostedTasks(): Promise<{
         tasks: A2ATaskEntry[];
@@ -378,8 +698,12 @@ export declare class BlindMarket {
     getReputation(address: Address): Promise<ReputationInfo>;
     /** Get top workers by decayed score. */
     getLeaderboard(limit?: number): Promise<LeaderboardEntry[]>;
-    /** Upload an encrypted blob to 0G Storage. */
-    uploadBlob(data: Hex): Promise<StorageUploadResult>;
+    /**
+     * Upload a blob to 0G Storage. `data` is the bytes as **base64**: the
+     * backend base64-decodes it. (The type once said Hex; a hex string sent
+     * here uploads the wrong bytes.)
+     */
+    uploadBlob(data: string): Promise<StorageUploadResult>;
     /**
      * Download a blob by root hash. `blob` is base64-encoded raw bytes — the
      * caller decodes (and, for encrypted tasks, decrypts) it client-side.