@supercuts-walrus/sdk 0.1.2 → 0.1.4

package/README.md

@@ -9,12 +9,108 @@ mandate and verifies payment evidence.
 subprocess seam. Wallet keys, state keys, witnesses, and service credentials stay
 inside the Supercuts process; the SDK receives intents and verified receipts.
 
-Install the SDK. It installs the matching backend runtime automatically:
+## Quick start: a new buyer on Testnet
+
+You need Node 22.13 or later and a Tatum API key. To use Walrus Memory you also need a Walrus Memory
+account (a delegate key, an account ID, and a Sui private key for client-side encryption) and
+[Ollama](https://ollama.com) with `embeddinggemma`.
+
+**1. Install.** The SDK installs the matching backend runtime. pnpm 10 and later block dependency build
+scripts by default, so allow `blake-hash` once. Its JavaScript fallback also works, but with pnpm 11 the
+blocked build makes `pnpm exec` refuse to run.
+
+```sh
+mkdir my-buyer && cd my-buyer && pnpm init
+printf 'allowBuilds:\n  blake-hash: true\n' > pnpm-workspace.yaml
+pnpm add @supercuts-walrus/sdk@0.1.4 @supercuts-walrus/backend@0.1.4
+```
+
+Add the backend explicitly. It provides the `supercuts`, `supercuts-embedding-adapter`, and
+`supercuts-memory-worker` commands, and pnpm only links commands from direct dependencies. With npm, run
+`npm install @supercuts-walrus/sdk@0.1.4 @supercuts-walrus/backend@0.1.4` instead; npm needs no build approval.
+
+**2. Store credentials in owner-only files.** Never paste them into an agent.
+
+```sh
+umask 077 && mkdir -p credentials
+printf '%s\n' "$TATUM_API_KEY" > credentials/tatum.key
+cat > credentials/memory.json <<JSON
+{ "key": "$MEMWAL_DELEGATE_KEY", "accountId": "$MEMWAL_ACCOUNT_ID", "suiPrivateKey": "$MEMWAL_SUI_PRIVATE_KEY" }
+JSON
+```
+
+Those three fields are all the Memory config needs. Supercuts fills in the Mainnet relayer, package,
+registry, and local adapter defaults, and gives each role its own namespace.
+
+**3. Start the embedding adapter** and leave it running. It pads local 768-dimensional vectors to the
+1536 dimensions that Walrus Memory requires:
+
+```sh
+ollama pull embeddinggemma
+pnpm exec supercuts-embedding-adapter
+```
+
+**4. Onboard the buyer.** Leave out any endpoint to use the public Testnet defaults and the shared
+seller directory:
+
+```sh
+cat > buyer-setup.json <<JSON
+{ "tatumKeyFile": "credentials/tatum.key", "memoryConfigFile": "credentials/memory.json",
+  "perDealCeiling": "2000000", "totalBudget": "10000000",
+  "expiresAt": $(( $(date +%s) * 1000 + 14 * 86400000 )), "allowPublicX402": true }
+JSON
+pnpm exec supercuts onboard buyer --home ./buyer --config buyer-setup.json
+```
+
+The output prints the generated buyer address and `nextSteps`. Fund only that address with Testnet SUI,
+using `supercuts funding execute … --request-faucet --confirm` or <https://faucet.sui.io>. Then review the
+directory and approve sellers:
 
 ```sh
-pnpm add @supercuts-walrus/sdk@0.1.2
+curl -s https://supercuts-sellers-testnet.onrender.com/v2/directory/catalog
+pnpm exec supercuts policy approve-seller --home ./buyer --capability-id market-brief-public-v2
+pnpm exec supercuts onboarding doctor --home ./buyer
 ```
 
+The npm package has everything public x402 payments need. Shielded payments additionally require the
+hash-pinned proving artifacts. Until those are installed, the doctor reports `shielded-proofs` as
+`unavailable`.
+
+**5. Run a deal.**
+
+```ts
+import { BuyerClient } from "@supercuts-walrus/sdk";
+
+const buyer = await BuyerClient.connect({ home: "./buyer", timeoutMs: 180_000 });
+const deal = await buyer.executeDeal({
+  operationId: "first-brief",                    // stable: reuse it to resume, never to pay twice
+  capabilityClass: "sui.market-brief",           // Walrus Memory ranks the matching sellers
+  input: { query: "Sui DeFi liquidity risks" },  // must fit the seller's signed input schema
+  budget: { asset: "0x2::sui::SUI", maximum: "1000000" },
+  requestedRail: "x402",
+});
+const evidence = await buyer.getDealEvidence(deal.dealId); // includes memoryInfluence
+const delivery = await buyer.getDealDelivery(deal.dealId);
+```
+
+Pick `input` from the seller's signed `inputSchema` (`buyer.listDealCapabilities()`). Discovery ignores
+sellers whose schema rejects your input. If a payment hits a transient seller-side outage, the error is
+`retryable`: call `executeDeal` or `resumeDeal` again with the **same** `operationId`. Never start a second
+payment.
+
+An MCP agent session flushes outcome memories in the background. An SDK-only host keeps the worker running
+next to the adapter, otherwise deals stay at `outcomeMemory: "pending"`:
+
+```sh
+pnpm exec supercuts-memory-worker ./buyer
+```
+
+Each finished deal writes a verified outcome to Walrus Memory. The next deal recalls it when choosing a
+seller, a rail, and a spend ceiling. `pnpm exec supercuts memory insights --home ./buyer` shows what the
+buyer has learned.
+
+## Lower-level API
+
 ```ts
 import { BuyerClient, initializeProfile } from "@supercuts-walrus/sdk";
 

package/dist/index.d.ts

@@ -62,6 +62,34 @@ export interface DealEvidenceView {
     inventory: "pending" | "indexed" | "missing" | "unresolved";
     paymentFinalized: boolean;
     paymentDigest?: string;
+    memoryInfluence?: {
+        changedSeller: boolean;
+        changedRail: boolean;
+        changedRisk: boolean;
+        changedMaximum: boolean;
+        withoutMemory?: MemoryDecision;
+        withMemory: MemoryDecision;
+        citedBlobIds: string[];
+    };
+    memoryRanking?: Array<{
+        capabilityId: string;
+        counterparty: string;
+        reliability: number;
+        observations: number;
+        successes: number;
+        failures: number;
+        unresolved: number;
+        lastOutcome?: string;
+        medianLatencyMs?: number;
+        priceMinimum: string;
+    }>;
+}
+export interface MemoryDecision {
+    sellerId: string;
+    capabilityId: string;
+    rail: string;
+    riskLevel: string;
+    maximumAmount: string;
 }
 export interface DealDelivery {
     dealId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supercuts-walrus/sdk",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Typed, role-scoped TypeScript SDK for Supercuts",
   "license": "Apache-2.0",
   "type": "module",
@@ -20,7 +20,7 @@
     "node": ">=22.13"
   },
   "dependencies": {
-    "@supercuts-walrus/backend": "0.1.2"
+    "@supercuts-walrus/backend": "0.1.4"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",