@escro/sdk 0.4.1 → 0.5.0

package/README.md

@@ -1,6 +1,11 @@
 # @escro/sdk
 
-TypeScript SDK for the [escro.ai](https://escro.ai) on-chain escrow protocol on Solana.
+TypeScript SDK for the [escro.ai](https://escro.ai) on-chain escrow protocol on Solana: escrow for
+bots. A Buyer Bot locks USDC, a Worker Bot delivers, and the contract enforces the state machine
+and defaults to refund. The SDK builds and signs the transactions and talks to the API; Escro never
+judges quality, the Buyer releases or disputes.
+
+Source: [github.com/escro-ai/escro.ai](https://github.com/escro-ai/escro.ai/tree/main/packages/sdk).
 
 ## Install
 
@@ -23,8 +28,10 @@ const client = new Escro({
 
 // Buyer: create and fund an escrow
 const { escrowPda, signature } = await client.createEscrow({
-  taskSpec: { /* ... */ },
-  amountUsdc: 10_000_000,  // 10 USDC
+  taskSpec: {
+    /* ... */
+  },
+  amountUsdc: 10_000_000, // 10 USDC
   deadlineUnix: Math.floor(Date.now() / 1000) + 3600,
   assignedWorker: "WorkerPubkeyBase58...",
 });
@@ -39,9 +46,67 @@ await client.submitDeliverable(items[0].address, {
 
 // Buyer: release payment or cancel
 await client.releasePayment(escrowPda);
-await client.cancelEscrow(escrowPda);  // only if FUNDED, before worker claims
+await client.cancelEscrow(escrowPda); // only if FUNDED, before worker claims
 ```
 
+## Spend cap
+
+A buyer sets `spendCap` when it constructs the client: the most micro-USDC its wallet may hold
+in open escrows, each counted as its deposit (amount plus fee).
+
+```typescript
+import { Escro, parseUsdc } from "@escro/sdk";
+
+const buyer = new Escro({
+  cluster: "mainnet",
+  rpcUrl: "https://api.mainnet-beta.solana.com",
+  apiUrl: "https://api.escro.ai",
+  wallet,
+  spendCap: { maxOutstandingMicroUsdc: parseUsdc("50") }, // 50 USDC
+});
+```
+
+Before the create is sent, `createEscrow` reads the on-chain fee rate and the wallet's open
+deposits (one `GET /v1/escrows/outstanding`: FUNDED, IN_PROGRESS, SUBMITTED and DISPUTED escrows),
+adds this process's creates still in flight, and throws `SPEND_CAP_EXCEEDED` for a create that
+would pass the cap. An outstanding read that fails, answers something malformed or takes longer
+than 15 s refuses the create with `SPEND_CAP_UNREADABLE` (a failed or timed-out read as its
+`cause`); a PlatformConfig read that fails or takes longer than 15 s throws its own error, with no
+code. On `"mainnet"` a client without `spendCap` cannot create (`SPEND_CAP_REQUIRED`); a
+worker-only client needs none. `spendCap.outstanding` replaces the API read under the same 15 s
+bound (one that has not answered is abandoned, not cancelled), and the in-flight creates are
+added to its answer. The error codes are exported as `SPEND_CAP_ERROR_CODES`. `createEscrow`
+also refuses an `assignedWorker` that is not a base-58 public key, or an
+`amountUsdc` that is not a positive whole number (`VALIDATION_ERROR`). The create request
+(`POST /v1/escrows`) is abandoned after 15 s with `API_TIMEOUT`.
+
+The cap holds per process. Every capped client for one wallet and cluster in the process shares one
+queue: creates are checked one at a time, and each holds its deposit as in flight from the API's
+answer to its POST. A create that throws before its transaction is sent (the SDK's refusal of the
+server's transaction as not the create it asked for, `UNEXPECTED_TRANSACTION`; an undecodable server
+transaction; a failed blockhash read) holds nothing. Once sent, the hold lasts until a successful
+`confirm(address, signature)`, or until evidence shows the transaction never took effect: the RPC
+rejected it other than as already processed, or it failed at execution (`TX_FAILED`). A create that
+throws after its transaction is sent for any other reason (a network error, a confirmation timeout,
+an `EscroConfirmError`) keeps counting, and shrinks the cap's room, until `confirm(address,
+signature)` succeeds or the process exits. An "already processed" rejection carries no signature to
+confirm with, so its hold lasts until the process exits. Two processes or hosts on one wallet each
+enforce the cap and together can pass it by the other's in-flight deposits: run one buyer process
+per wallet, or give each its share.
+
+## Paying a 402
+
+A `pay()` given an address rule (`admitAddress`) needs direct egress and local DNS: it resolves each
+host with this machine's resolver and connects directly to the addresses the rule admitted, ignoring
+any HTTP or HTTPS proxy set in the environment. With `url`, on a network reachable only through a
+proxy the pay fails at its first request, before anything is funded or signed. With
+`paymentRequired`, a `resource.url` whose host resolves here but cannot be reached directly fails at
+the paid request, after the escrow is funded or the `exact` payment signed.
+
+`pay()` refuses a `url`, or with `paymentRequired` the 402's `resource.url`, on a port `fetch` blocks
+(25, 6667 and the rest of the Fetch standard's bad-port list) before any lookup or request, and the default job-specification read refuses a
+`specUri` that carries a username or password or names such a port.
+
 ## API
 
 Every method, its parameters and its errors are in the generated