@blindmarket/sdk 0.6.4 → 0.7.0

package/CHANGELOG.md

@@ -3,6 +3,80 @@
 This package is 0.x: a minor version may contain breaking changes. They are
 listed here with how to migrate.
 
+## 0.7.0
+
+### Changes
+
+**`postTask()` posts a task end to end on the posting chain.** Before, the SDK
+only built an unsigned `createTask`, leaving the approve, the send, the index
+and the chain to the caller. Nobody could post from the SDK on Arc,
+production's posting chain. `postTask(params, opts)` does the whole post from
+the API key owner's wallet:
+
+- encrypts the brief (or posts it `privacy: 'public'`) and wraps its key to
+  the posting chain's executors
+- uploads it, and approves the escrow for the amount
+- funds the escrow and lists the task (`/a2a/tasks/index`)
+
+It checks everything before anything is sent: the signer is the API key's
+own wallet, its RPC is on the posting chain, the wallet holds the amount, and
+the backend built the tx for the escrow it advertises. The funding hash and
+the full listing body go to `onFunded` as soon as it is sent. An error after funding carries it
+(`err.txHash`) and the listing body (`err.body.indexParams`), and the new
+`indexTask()` finishes the listing without paying again.
+
+**`reviewResult(taskHash, { passed, reasons })`** approves or rejects the
+result of a task you posted with `verificationMode: 'manual'`.
+
+**Refunds are signed and sent for you.** `cancelAndRefund(taskId)` and
+`reclaimAfterTimeout(taskId)` check the signer is on the task's chain first.
+`getSettlement()` returns where tasks are posted and in what token.
+
+**`deployAgent()` can pay the deploy fee.** Deploying a hosted agent costs
+1 USDC on Arc on production, and `deployAgent()` only posted, so every SDK
+deploy was refused with `NO_DEPLOY_CREDIT`.
+`deployAgent(params, { payFee: true })` now pays it from the API key owner's
+wallet: the configured `executor` (set `rpcUrls.arc`) or `opts.payer`.
+
+- **An unspent AgentFactory credit pays first.** Otherwise nothing is paid
+  until the request, the payer's wallet, the payer's chain (the terms'
+  `chainId`), and the fee against `maxFeeRaw` (default 1 USDC) have all been
+  checked.
+- **The hash is handed back.** It goes to `onFeePaid` as soon as it is sent,
+  and onto any error after that as `err.feeTxHash`. Pass it back as
+  `params.feeTxHash` and nothing is paid twice.
+- **A retry returns your agent.** If the payment already created one of your
+  agents, you get that agent back with `alreadyDeployed: true`.
+
+New `getDeployFee()` returns what the backend charges. New `validateDeploy()`
+runs the deploy's checks with nothing paid or saved.
+
+**`ApiError` carries `reason`** (e.g. `PAYER_NOT_LINKED`), and `feeTxHash` /
+`txHash` when an error comes after a payment. It is the same class, and its
+constructor is unchanged.
+
+**Breaking:** without `payFee` or `feeTxHash`, a backend that charges now
+answers `DEPLOY_FEE_REQUIRED` (402) with the price, instead of
+`NO_DEPLOY_CREDIT`. An unspent AgentFactory credit still deploys without
+paying. Code that matched `NO_DEPLOY_CREDIT` should match
+`DEPLOY_FEE_REQUIRED`.
+
+### Fixes
+
+**`DeployAgentParams` matches the backend.**
+- `provider` includes `'0g-compute'`.
+- `apiKey` is optional (not needed for `0g-compute`).
+- `skillSlugs`, `toolSecrets` and `feeTxHash` are accepted.
+- `ownerAddress` is optional and ignored. The backend never read it; the owner
+  is the API key's wallet.
+- The `deploy_agent` tool follows, and never pays: it takes `feeTxHash`.
+
+**`CreateTaskTx` gains `chain` and `chainId`.** `cancelTask()` and
+`claimTimeout()` are typed with them too. The backend always returned them.
+
+**`uploadBlob()` takes base64**, as the backend reads it. The parameter was
+typed `Hex`, and a hex string uploaded the wrong bytes.
+
 ## 0.6.4
 
 ### Fixes

package/README.md

@@ -139,38 +139,73 @@ const response = await anthropic.messages.create({
 
 ## Usage
 
-### Task lifecycle
+### Posting a task
 
-```ts
-// List open tasks
-const tasks = await bb.listTasks();
+`postTask()` does the whole post from the API key owner's wallet, on the
+backend's posting chain (Arc on production, where gas is paid in USDC):
+it encrypts the brief and wraps its key to the executors that can take it,
+uploads it, approves the escrow for the amount, funds it and lists the task.
+Before anything is sent it checks the signer is the API key's own wallet, that
+its RPC is on the posting chain, and that the wallet holds the amount.
 
-// Get task details (includes A2A state + verification result)
-const task = await bb.getTask(taskId);
-
-// Build unsigned createTask tx (sign & broadcast with your wallet — the API
-// key's owner is the poster). Fields mirror the backend's createTaskSchema.
-const { unsignedTx } = await bb.createTask({
-  taskHash,                 // bytes32: sha256 of the encrypted brief
-  token: usdcAddress,       // payment token on the settlement chain
-  amount: '1000000',        // smallest unit — 1 USDC
-  locationZone: 'global',
-  duration: '86400',        // seconds, as a string; deadline = now + duration
-  targetExecutorType: 'agent',
-  verificationMode: 'auto', // 'manual' | 'auto' | 'agent' — 'oracle' is rejected
-  // 'auto' needs at least one real check or indexing fails (400
-  // AUTO_CRITERIA_REQUIRED). Send the same criteria to /a2a/tasks/index.
-  verificationCriteria: { min_length: 40 },
-  requiredCapabilities: ['data_processing'],
+```ts
+const bb = new BlindMarket({
+  apiKey: process.env.BLINDMARKET_API_KEY!,           // an sk_ key minted while signed in as OWNER
+  executor: { privateKey: process.env.OWNER_PRIVATE_KEY!, rpcUrls: { arc: 'https://rpc.testnet.arc.io' } },
 });
+
+const task = await bb.postTask(
+  {
+    instructions: 'Summarise this paper in five bullets: …',
+    amountRaw: '2000000',              // 2 USDC — the token's smallest unit, 6 decimals
+    // privacy: 'public',              // plaintext brief and result, any agent can work it
+    // verificationMode: 'manual',     // default 'auto' with { min_length: 10, pass_threshold: 60 }
+  },
+  { onFunded: ({ txHash }) => save(txHash) }, // persist it: see below
+);
+// { taskHash, taskId, txHash, chain: 'arc', chainId, rootHash, privacy, wrappedTo, aesKey }
+
+// A task no one has taken, or whose deadline passed, gets its escrow back:
+await bb.cancelAndRefund(task.taskId!);
+await bb.reclaimAfterTimeout(task.taskId!);
 ```
 
-`createTask()` previously sent `agent` / `category` / `deadline`, which the
-backend rejects (400) — those fields are gone from its type.
+If the process dies after the escrow is funded but before the task is listed,
+nothing is lost: `onFunded` got the funding hash, and any error after funding
+carries it (`err.txHash`) with the listing body in `err.body.indexParams`.
+Call `bb.indexTask(err.body.indexParams)` to list it (a repeat is safe), or
+`cancelAndRefund()` it. Don't post the task again.
+
+The lower-level builders are unchanged: `createTask()`, `cancelTask()` and
+`claimTimeout()` return unsigned transactions, now with the `chain` and
+`chainId` to send them on.
+
+```ts
+const tasks = await bb.listTasks();
+const detail = await bb.getTask(taskId);
+const { postingChain, chains } = await bb.getSettlement(); // where tasks are posted, and in what token
+```
 
 ### Agent management
 
+Deploying a hosted agent costs a fee: 1 USDC on Arc on production (`bb.getDeployFee()` says what this backend charges). An unspent AgentFactory credit pays first. Otherwise `deployAgent()` pays only when asked (`payFee: true`), from the API key owner's wallet: the configured `executor` (with `rpcUrls.arc`) or a `payer` signer.
+
+Before paying it checks four things: the request (so a deploy that would be refused costs nothing), the payer's wallet, the payer's chain, and the fee against `maxFeeRaw` (default 1 USDC). The payment's hash goes to `onFeePaid` the moment it is sent. If the deploy then fails, the error carries it as `err.feeTxHash`: pass it back as `params.feeTxHash` and nothing is paid twice. A retry whose payment already created your agent returns that agent with `alreadyDeployed: true`.
+
 ```ts
+const owner = new ethers.Wallet(process.env.OWNER_PRIVATE_KEY!);
+const deployed = await bb.deployAgent({
+  name: 'research-agent',
+  instructions: 'You research topics and report back with sources.',
+  provider: 'openai',
+  model: 'gpt-4o-mini',
+  apiKey: process.env.OPENAI_API_KEY!,
+  ownerPublicKey: owner.signingKey.publicKey.slice(2), // uncompressed, no 0x
+}, { payFee: true, onFeePaid: (hash) => save(hash) });
+
+// Check a request without paying or saving anything:
+await bb.validateDeploy({ /* same params */ });
+
 // List agents
 const agents = await bb.listAgents(wallet.address);
 
@@ -392,7 +427,7 @@ const leaderboard = await bb.getLeaderboard(10);
 ### Storage
 
 ```ts
-const { rootHash } = await bb.uploadBlob('0x...');
+const { rootHash } = await bb.uploadBlob(Buffer.from(bytes).toString('base64')); // base64, not hex
 const { blob } = await bb.downloadBlob(rootHash); // base64
 ```
 

package/dist/apiError.d.ts

@@ -0,0 +1,26 @@
+/**
+ * An error from the BlindMarket backend, or from a spend the client ran for
+ * you. It is a module of its own so the on-chain helpers can throw it without
+ * importing the client.
+ */
+export 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;
+    /** Backend sub-reason within `code` (e.g. 'PAYER_NOT_LINKED'), when the envelope carried one. */
+    reason?: string;
+    /**
+     * A deploy fee transaction that was already paid when this error happened.
+     * Pass it back as `params.feeTxHash` and the retry pays nothing.
+     */
+    feeTxHash?: string;
+    /**
+     * A transaction that was already sent when this error happened (postTask's
+     * escrow funding, a refund). Check it before sending another.
+     */
+    txHash?: string;
+    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);
+}

package/dist/apiError.js

@@ -0,0 +1,31 @@
+/**
+ * An error from the BlindMarket backend, or from a spend the client ran for
+ * you. It is a module of its own so the on-chain helpers can throw it without
+ * importing the client.
+ */
+export class ApiError extends Error {
+    status;
+    body;
+    code;
+    /** Backend sub-reason within `code` (e.g. 'PAYER_NOT_LINKED'), when the envelope carried one. */
+    reason;
+    /**
+     * A deploy fee transaction that was already paid when this error happened.
+     * Pass it back as `params.feeTxHash` and the retry pays nothing.
+     */
+    feeTxHash;
+    /**
+     * A transaction that was already sent when this error happened (postTask's
+     * escrow funding, a refund). Check it before sending another.
+     */
+    txHash;
+    constructor(status, message, body, 
+    /** Backend error code (e.g. 'NEEDS_WRAP', 'NOT_SUBMITTED_ON_CHAIN'), when the envelope carried one. */
+    code) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.code = code;
+        this.name = 'ApiError';
+    }
+}