@supercuts-walrus/backend 0.0.0-stage → 0.1.0

package/dist/live-deal-ports.js

@@ -0,0 +1,212 @@
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { verifySignedCapability } from "./capability.js";
+import { WalrusDealBlobs, wireDecrypt, wireEncrypt, wireHash, wireJsonHash, wireKey } from "./deal-wire.js";
+import { fail } from "./errors.js";
+import { LiveRuntime } from "./live-runtime.js";
+import { executeMandated } from "./mandate.js";
+import { canonicalJson, settlementMandateHash, validateSettlementPlan } from "./settlement.js";
+import { validateDirectoryOrigin } from "./seller-directory.js";
+const halves = (hash) => [BigInt(`0x${hash.slice(0, 32)}`).toString(), BigInt(`0x${hash.slice(32)}`).toString()];
+const scalar = () => BigInt(`0x${randomBytes(16).toString("hex")}`).toString();
+const offerSignatureBytes = (sessionId, capabilityId, buyerPublicKey, ciphertext) => Buffer.from(`${sessionId}:${capabilityId}:${buyerPublicKey}:${wireHash(Buffer.from(ciphertext, "base64"))}`);
+/** Built-in live buyer adapter. The owner supplies only seller catalog origins;
+ * signing, payment, Walrus and memory stay in the buyer role home. */
+export class LiveDealPorts {
+    app;
+    mandate;
+    http;
+    #blobs;
+    #origins;
+    #directory;
+    constructor(app, mandate, http = fetch) {
+        this.app = app;
+        this.mandate = mandate;
+        this.http = http;
+        if (app.profile.role !== "buyer" || app.profile.mock)
+            fail("DEAL_LIVE_REQUIRED", "built-in deal adapter requires a live buyer role");
+        const path = join(app.home, "deal-sellers.json");
+        let source;
+        try {
+            if ((statSync(path).mode & 0o077) !== 0)
+                fail("DEAL_SELLERS_PERMISSIONS", "seller catalog configuration must be owner-only");
+            source = JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch (error) {
+            return fail("DEAL_SELLERS_NOT_CONFIGURED", "buyer requires owner-only deal-sellers.json containing seller origins", error);
+        }
+        const config = Array.isArray(source) ? { origins: source } : source;
+        if (!config || !Array.isArray(config.origins) || config.origins.length > 32 || !config.origins.length && !config.directoryUrl)
+            return fail("DEAL_SELLERS_INVALID", "seller configuration requires a directory or 1..32 origins");
+        this.#origins = config.origins.map((value) => {
+            const url = new URL(String(value));
+            if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(url.hostname)) || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+                fail("DEAL_SELLERS_INVALID", "seller origin must be HTTPS or loopback HTTP without path or credentials");
+            return url;
+        });
+        if (config.directoryUrl) {
+            const url = new URL(config.directoryUrl);
+            if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(url.hostname)) || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+                fail("DEAL_SELLERS_INVALID", "directory URL must be an HTTPS or loopback origin");
+            this.#directory = url;
+        }
+        this.#blobs = new WalrusDealBlobs(app, http);
+    }
+    readBlob(blobId) { return this.#blobs.read(blobId); }
+    signer() {
+        const encoded = this.app.store.getSecret("live:sui-private-key")?.toString() ?? fail("LIVE_CREDENTIAL_MISSING", "buyer signer is missing");
+        const decoded = decodeSuiPrivateKey(encoded);
+        if (decoded.scheme !== "ED25519")
+            fail("SIGNER_UNSUPPORTED", "buyer requires an ED25519 signer");
+        return Ed25519Keypair.fromSecretKey(decoded.secretKey);
+    }
+    async request(origin, path, body) {
+        const response = await this.http(new URL(path, origin), { ...(body ? { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) } : {}), redirect: "error", signal: AbortSignal.timeout(90_000) });
+        let value;
+        try {
+            value = await response.json();
+        }
+        catch (error) {
+            return fail("DEAL_SELLER_RESPONSE_INVALID", "seller response is not JSON", error);
+        }
+        if (!response.ok || !value || typeof value !== "object" || Array.isArray(value))
+            fail("DEAL_SELLER_RESPONSE_INVALID", `seller returned HTTP ${response.status}`);
+        return value;
+    }
+    async catalog() {
+        const found = [];
+        const sources = this.#origins.map((origin) => ({ origin, path: "/v2/catalog" }));
+        if (this.#directory)
+            sources.push({ origin: this.#directory, path: "/v2/directory/catalog" });
+        for (const { origin, path } of sources) {
+            let offset = 0;
+            do {
+                const catalog = await this.request(origin.toString(), path === "/v2/directory/catalog" ? `${path}?offset=${offset}` : path);
+                if (!Array.isArray(catalog.capabilities) || catalog.capabilities.length > 100)
+                    fail("SELLER_CATALOG_INVALID", "seller catalog is invalid");
+                for (const item of catalog.capabilities) {
+                    const registration = item;
+                    await verifySignedCapability(registration);
+                    if (path === "/v2/catalog" && new URL(registration.manifest.endpoint).origin !== origin.origin)
+                        fail("SELLER_CATALOG_INVALID", "signed capability points outside catalog seller origin");
+                    if (!this.mandate.allowedCounterparties.includes(registration.manifest.sellerId) || this.mandate.allowedCapabilityIds && !this.mandate.allowedCapabilityIds.includes(registration.manifest.capabilityId) || this.mandate.allowedCapabilityClasses && !this.mandate.allowedCapabilityClasses.includes(registration.manifest.capability))
+                        continue;
+                    if (path === "/v2/directory/catalog") {
+                        const endpoint = await validateDirectoryOrigin(registration.manifest.endpoint);
+                        const served = await this.request(endpoint.origin, "/v2/catalog");
+                        if (!Array.isArray(served.capabilities) || !served.capabilities.some((item) => canonicalJson(item) === canonicalJson(registration)))
+                            fail("SELLER_CATALOG_INVALID", "directory listing is no longer served by the seller");
+                    }
+                    const readback = await this.readBlob(registration.manifestBlobId);
+                    if (canonicalJson(JSON.parse(Buffer.from(readback).toString())) !== canonicalJson(registration.manifest))
+                        fail("CAPABILITY_BLOB_MISMATCH", "Walrus capability blob differs from signed manifest");
+                    found.push({ origin: new URL(registration.manifest.endpoint).origin, registration });
+                }
+                if (path !== "/v2/directory/catalog" || catalog.nextOffset === undefined)
+                    break;
+                if (catalog.nextOffset !== offset + 100 || catalog.capabilities.length !== 100)
+                    fail("SELLER_CATALOG_INVALID", "directory pagination is invalid");
+                offset = catalog.nextOffset;
+                if (offset > 100_000)
+                    fail("SELLER_CATALOG_INVALID", "directory contains too many listings");
+            } while (true);
+        }
+        return found;
+    }
+    async discover(input) {
+        const candidates = (await this.catalog()).map(({ registration }) => registration).filter((registration) => (input.capabilityId && registration.manifest.capabilityId === input.capabilityId || input.capabilityClass && registration.manifest.capability === input.capabilityClass) && registration.manifest.asset === input.budget.asset);
+        if (!candidates.length)
+            fail("DEAL_CAPABILITY_NOT_FOUND", "configured sellers have no matching signed capability");
+        candidates.sort((a, b) => BigInt(a.manifest.priceBand.minimum) < BigInt(b.manifest.priceBand.minimum) ? -1 : BigInt(a.manifest.priceBand.minimum) > BigInt(b.manifest.priceBand.minimum) ? 1 : a.manifest.capabilityId.localeCompare(b.manifest.capabilityId));
+        return candidates[0];
+    }
+    async plan(input, registration, paymentOperationId) {
+        const existing = this.app.store.db.prepare("SELECT plan_json FROM settlement_plans WHERE operation_id=?").get(paymentOperationId);
+        if (existing) {
+            const saved = JSON.parse(existing.plan_json);
+            validateSettlementPlan(saved);
+            if (saved.mandateHash !== settlementMandateHash(this.mandate) || saved.manifestHash !== registration.manifest.manifestHash || saved.operationId !== paymentOperationId)
+                fail("DEAL_PLAN_MISMATCH", "persisted plan differs from the owner mandate or seller capability");
+            return saved;
+        }
+        const result = await executeMandated(this.app, this.mandate, "settlement.plan", { "operation-id": paymentOperationId, manifest: registration.manifest, "requested-amount": registration.manifest.priceBand.minimum, ...(input.privacyHint ? { "privacy-hint": input.privacyHint } : {}), ...(input.requestedRail ? { "requested-rail": input.requestedRail } : {}) });
+        return result;
+    }
+    async negotiate(input, registration, plan, agreementOperationId) {
+        const sessionId = agreementOperationId, capabilityId = registration.manifest.capabilityId, buyerPublicKey = this.app.store.getSecret("identity:x25519-public")?.toString("base64url") ?? fail("IDENTITY_MISSING", "buyer transport key is missing");
+        const key = wireKey(this.app, registration.transportPublicKey, sessionId), taskHash = wireJsonHash(input.input), amount = registration.manifest.priceBand.minimum;
+        const transcript = wireJsonHash({ domain: "supercuts-deal-transcript-v1", sessionId, taskHash, planHash: plan.planHash, amount, rail: plan.rail });
+        const service = wireJsonHash({ domain: "supercuts-deal-service-v1", taskHash, planHash: plan.planHash, capabilityId, rail: plan.rail, buyerPublicKey });
+        const [transcriptRootLo, transcriptRootHi] = halves(transcript), [serviceDigestLo, serviceDigestHi] = halves(service);
+        const secretKey = `deal:wire:offer:${sessionId}`;
+        let ciphertext = this.app.store.getSecret(secretKey)?.toString();
+        if (!ciphertext) {
+            const runtime = await LiveRuntime.create(this.app.profile, this.app.store);
+            const buyer = runtime.engine.identity(this.app.store.getSecret("identity:babyjub-seed") ?? fail("IDENTITY_MISSING", "buyer settlement identity is missing"));
+            const draft = { sessionId, dealOperationId: input.operationId, capabilityId, manifestHash: registration.manifest.manifestHash, counterparty: registration.manifest.sellerId, paymentAmount: amount, rail: plan.rail, taskHash, planHash: plan.planHash, dealId: scalar(), revision: "1", transcriptRootLo, transcriptRootHi, serviceDigestLo, serviceDigestHi, settlementNonceLo: scalar(), settlementNonceHi: scalar(), blinding: scalar(), expiry: String(Math.min(plan.expiresAt, Date.now() + 30 * 60_000)), buyerPublicKey: buyer.publicKey.map(String) };
+            ciphertext = wireEncrypt(key, sessionId, "offer", { input: input.input, planHash: plan.planHash, paymentOperationId: plan.operationId, amount, maximum: plan.maximumAmount, rail: plan.rail, draft });
+            this.app.store.putSecretOnce(secretKey, Buffer.from(ciphertext));
+        }
+        const signer = this.signer(), signature = (await signer.signPersonalMessage(offerSignatureBytes(sessionId, capabilityId, buyerPublicKey, ciphertext))).signature;
+        const origin = new URL(registration.manifest.endpoint).origin;
+        const reply = await this.request(origin, "/v2/prepare", { sessionId, capabilityId, dealOperationId: input.operationId, buyerAddress: signer.toSuiAddress(), buyerPublicKey, buyerSignature: signature, ciphertext });
+        if (reply.sessionId !== sessionId || reply.capabilityId !== capabilityId || typeof reply.ciphertext !== "string")
+            return fail("DEAL_SELLER_RESPONSE_INVALID", "seller changed the prepared deal identity");
+        const offerBlob = reply.offerBlob, replyBlob = reply.replyBlob, agreementBlob = reply.agreementBlob;
+        if (wireHash(await this.readBlob(offerBlob.blobId)) !== offerBlob.ciphertextHash || offerBlob.ciphertextHash !== wireHash(Buffer.from(ciphertext, "base64")) || wireHash(await this.readBlob(replyBlob.blobId)) !== replyBlob.ciphertextHash || replyBlob.ciphertextHash !== wireHash(Buffer.from(reply.ciphertext, "base64")) || agreementBlob.blobId !== replyBlob.blobId || agreementBlob.ciphertextHash !== replyBlob.ciphertextHash)
+            fail("WALRUS_BLOB_MISMATCH", "seller transcript differs from encrypted Walrus evidence");
+        const decoded = wireDecrypt(key, sessionId, "reply", reply.ciphertext);
+        if (plan.rail === "x402" && decoded.resourceUrl !== `${registration.manifest.endpoint.replace(/\/$/, "")}/${encodeURIComponent(sessionId)}` || plan.rail === "shielded" && decoded.resourceUrl)
+            fail("DEAL_RESOURCE_MISMATCH", "seller returned a resource outside the signed capability endpoint");
+        const rawAgreement = Buffer.from(decoded.agreement, "base64url").toString(), agreement = JSON.parse(rawAgreement);
+        if (wireHash(rawAgreement) !== decoded.agreementHash || agreement.sessionId !== sessionId || agreement.dealOperationId !== input.operationId || agreement.capabilityId !== capabilityId || agreement.manifestHash !== registration.manifest.manifestHash || agreement.counterparty !== registration.manifest.sellerId || agreement.paymentAmount !== amount || agreement.rail !== plan.rail || agreement.taskHash !== taskHash || agreement.planHash !== plan.planHash || agreement.transcriptRootLo !== transcriptRootLo || agreement.transcriptRootHi !== transcriptRootHi || agreement.serviceDigestLo !== serviceDigestLo || agreement.serviceDigestHi !== serviceDigestHi)
+            fail("AGREEMENT_BINDING_MISMATCH", "seller signed different deal terms");
+        const accepted = await executeMandated(this.app, this.mandate, "offer.accept", { "operation-id": `accept-${sessionId}`, session: sessionId, agreement: decoded.agreement, ...(plan.rail === "shielded" ? { "plan-hash": plan.planHash } : {}) });
+        if (accepted.dealCommitment !== decoded.dealCommitment)
+            fail("AGREEMENT_BINDING_MISMATCH", "seller commitment differs from accepted agreement");
+        return { sessionId, agreementHash: decoded.agreementHash, agreedAmount: amount, sellerOrigin: origin, sellerTransportPublicKey: registration.transportPublicKey, ...(decoded.resourceUrl ? { resourceUrl: decoded.resourceUrl } : {}), transcriptBlobs: [offerBlob, replyBlob], agreementBlobId: agreementBlob.blobId, agreementCiphertextHash: agreementBlob.ciphertextHash };
+    }
+    async pay(input, plan, negotiation, paymentOperationId) {
+        const prepared = negotiation;
+        if (!prepared.sessionId || !prepared.agreementHash || prepared.agreedAmount !== plan.manifestMinimum)
+            fail("DEAL_AGREEMENT_INVALID", "saved negotiation is missing exact payment terms");
+        const result = plan.rail === "shielded" ? await executeMandated(this.app, this.mandate, "pay.shielded", { "operation-id": paymentOperationId, session: prepared.sessionId, "plan-hash": plan.planHash }) : await executeMandated(this.app, this.mandate, "pay.x402", { "operation-id": paymentOperationId, "resource-url": prepared.resourceUrl ?? fail("DEAL_RESOURCE_MISSING", "seller did not provide an x402 protected resource"), "plan-hash": plan.planHash });
+        if (result.finalized !== true || result.tatumVerified !== true || result.rail !== plan.rail || result.amount !== prepared.agreedAmount || result.counterparty !== plan.sellerId || result.asset !== plan.asset || typeof result.transactionDigest !== "string")
+            return fail("DEAL_PAYMENT_UNVERIFIED", "live payment differs from the accepted agreement and settlement plan");
+        if (plan.rail === "x402") {
+            const response = JSON.parse(Buffer.from(String(result.response ?? ""), "base64").toString());
+            if (response.status !== "paid" || response.requestId !== prepared.sessionId)
+                fail("DEAL_PAYMENT_UNVERIFIED", "seller-owned x402 resource returned a different receipt");
+        }
+        return { transactionDigest: result.transactionDigest, finalized: true, tatumVerified: true, ...(typeof result.proveMs === "number" ? { proveMs: result.proveMs } : {}) };
+    }
+    async deliver(input, plan, negotiation, payment, _deliveryOperationId) {
+        const prepared = negotiation, key = wireKey(this.app, prepared.sellerTransportPublicKey, prepared.sessionId);
+        const request = { dealId: input.operationId, capabilityId: plan.capabilityId, input: input.input, requestId: prepared.sessionId, paymentDigest: payment.transactionDigest, agreementHash: prepared.agreementHash, agreedAmount: prepared.agreedAmount, rail: plan.rail };
+        const ciphertext = wireEncrypt(key, prepared.sessionId, "fulfill", request), signer = this.signer();
+        const signature = (await signer.signPersonalMessage(Buffer.from(`${prepared.sessionId}:${wireHash(Buffer.from(ciphertext, "base64"))}`))).signature;
+        const reply = await this.request(prepared.sellerOrigin, "/v2/fulfill", { sessionId: prepared.sessionId, sellerId: plan.sellerId, ciphertext, buyerSignature: signature });
+        if (reply.sessionId !== prepared.sessionId || typeof reply.ciphertext !== "string")
+            return fail("DEAL_DELIVERY_UNVERIFIED", "seller delivery response is invalid");
+        const receipt = wireDecrypt(key, prepared.sessionId, "receipt", reply.ciphertext);
+        if (receipt.dealId !== input.operationId || receipt.requestId !== prepared.sessionId)
+            fail("DEAL_DELIVERY_UNVERIFIED", "seller delivery belongs to another deal");
+        const encrypted = await this.readBlob(receipt.blobId);
+        if (wireHash(encrypted) !== receipt.ciphertextHash)
+            fail("WALRUS_BLOB_MISMATCH", "seller delivery ciphertext differs from Walrus");
+        const artifact = wireDecrypt(key, prepared.sessionId, "delivery", Buffer.from(encrypted).toString("base64"));
+        if (wireHash(Buffer.from(artifact.artifactBase64, "base64")) !== receipt.artifactSha256 || artifact.contentType !== receipt.contentType || canonicalJson(artifact.metadata) !== canonicalJson(receipt.metadata))
+            fail("DEAL_DELIVERY_UNVERIFIED", "seller delivery bytes or metadata differ from the receipt");
+        return { blobId: receipt.blobId, ciphertextHash: receipt.ciphertextHash, artifactSha256: receipt.artifactSha256, contentType: receipt.contentType, metadata: receipt.metadata, artifactBase64: artifact.artifactBase64 };
+    }
+    async rememberOutcome(input, plan, payment, artifact, _outcomeOperationId) {
+        return this.app.recordVerifiedDealOutcome(input.operationId, plan.planHash, payment.transactionDigest, artifact.artifactSha256);
+    }
+    async inventory(blobId) {
+        const result = (await this.app.execute("memory.inventory", { "blob-id": blobId })).data;
+        return result.present === true;
+    }
+}

package/dist/live-index.d.ts

@@ -0,0 +1,28 @@
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { ProtocolEngine } from "./protocol-engine.js";
+import { RoleStore } from "./store.js";
+export interface LiveIndexState {
+    leaves: bigint[];
+    root: bigint;
+    nextLeaf: bigint;
+    lastCheckpoint: bigint;
+    transactions: string[];
+    activity?: {
+        deposits: number;
+        exits: number;
+        distinctDepositingAddresses: number;
+        reducedPrivacy: boolean;
+    };
+}
+export declare class LivePoolIndex {
+    private readonly store;
+    private readonly client;
+    private readonly engine;
+    private readonly packageId;
+    private readonly poolId;
+    private readonly deploymentCheckpoint;
+    private readonly moduleName;
+    constructor(store: RoleStore, client: SuiGrpcClient, engine: ProtocolEngine, packageId: string, poolId: string, deploymentCheckpoint: bigint, moduleName?: "pool" | "pool_v2");
+    cached(): LiveIndexState | undefined;
+    sync(): Promise<LiveIndexState>;
+}

package/dist/live-index.js

@@ -0,0 +1,149 @@
+import { fail } from "./errors.js";
+const hexVector = (value, name) => {
+    if (typeof value !== "string")
+        return fail("CHAIN_EVENT_INVALID", `${name} is missing from a pool event`);
+    const bytes = /^(?:0x)?[0-9a-f]{64}$/i.test(value) ? Buffer.from(value.replace(/^0x/, ""), "hex") : Buffer.from(value, "base64");
+    if (bytes.length !== 32)
+        return fail("CHAIN_EVENT_INVALID", `${name} is not 32 bytes`);
+    return bytes.toString("hex");
+};
+const integer = (value, name) => { if (typeof value !== "string" && typeof value !== "number")
+    return fail("CHAIN_EVENT_INVALID", `${name} is missing`); try {
+    return BigInt(value);
+}
+catch (error) {
+    return fail("CHAIN_EVENT_INVALID", `${name} is invalid`, error);
+} };
+const transaction = (result) => {
+    const value = result;
+    return value.Transaction ?? value.FailedTransaction ?? fail("CHAIN_TRANSACTION_INVALID", "transaction response is empty");
+};
+export class LivePoolIndex {
+    store;
+    client;
+    engine;
+    packageId;
+    poolId;
+    deploymentCheckpoint;
+    moduleName;
+    constructor(store, client, engine, packageId, poolId, deploymentCheckpoint, moduleName = "pool") {
+        this.store = store;
+        this.client = client;
+        this.engine = engine;
+        this.packageId = packageId;
+        this.poolId = poolId;
+        this.deploymentCheckpoint = deploymentCheckpoint;
+        this.moduleName = moduleName;
+        store.db.exec(`
+      CREATE TABLE IF NOT EXISTS live_pool_leaves (leaf_index TEXT PRIMARY KEY, commitment TEXT NOT NULL, transaction_digest TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS live_pool_sync (singleton INTEGER PRIMARY KEY CHECK(singleton=1), root TEXT NOT NULL, next_leaf TEXT NOT NULL, checkpoint TEXT NOT NULL, synced_at INTEGER NOT NULL);
+    `);
+    }
+    cached() {
+        const sync = this.store.db.prepare("SELECT root,next_leaf,checkpoint FROM live_pool_sync WHERE singleton=1").get();
+        if (!sync)
+            return undefined;
+        const rows = this.store.db.prepare("SELECT leaf_index,commitment,transaction_digest FROM live_pool_leaves ORDER BY CAST(leaf_index AS INTEGER)").all();
+        const leaves = [];
+        for (const row of rows) {
+            if (BigInt(row.leaf_index) !== BigInt(leaves.length))
+                fail("POOL_CACHE_INVALID", "cached leaves are not contiguous");
+            leaves.push(BigInt(`0x${row.commitment}`));
+        }
+        return { leaves, root: BigInt(`0x${sync.root}`), nextLeaf: BigInt(sync.next_leaf), lastCheckpoint: BigInt(sync.checkpoint), transactions: rows.map((row) => row.transaction_digest) };
+    }
+    async sync() {
+        const leaves = [], transactions = [], leafTransactions = [];
+        const depositingAddresses = new Set(), seenTransactions = new Set();
+        let deposits = 0, exits = 0;
+        let cursor = null, checkpoint = this.deploymentCheckpoint, expectedRoot = BigInt(`0x${this.engine.deployment.initialRoot.replace(/^0x/, "")}`), guard = 0;
+        do {
+            if (++guard > 100_000)
+                fail("CHAIN_PAGINATION_INVALID", "pool history pagination did not terminate");
+            const page = await this.client.listTransactions({ filter: { function: `${this.packageId}::${this.moduleName}` }, limit: 50, after: cursor, order: "ascending", include: { effects: true, events: true, transaction: true } });
+            for (const result of page.transactions) {
+                const tx = transaction(result);
+                if (!tx.checkpoint || BigInt(tx.checkpoint) < this.deploymentCheckpoint || !tx.status.success)
+                    continue;
+                if (!tx.effects?.changedObjects.some((object) => object.objectId.toLowerCase() === this.poolId.toLowerCase()))
+                    continue;
+                if (!tx.digest || seenTransactions.has(tx.digest) || BigInt(tx.checkpoint) < checkpoint)
+                    fail("POOL_HISTORY_INVALID", "pool transaction history contains a duplicate or is out of checkpoint order");
+                seenTransactions.add(tx.digest);
+                let touched = false;
+                for (const event of tx.events ?? []) {
+                    if (event.packageId.toLowerCase() !== this.packageId.toLowerCase() || event.module !== this.moduleName || !event.json)
+                        continue;
+                    const value = event.json, name = event.eventType.split("::").pop();
+                    if (name === "DepositEvent") {
+                        const oldRoot = BigInt(`0x${hexVector(value.old_root, "old_root")}`), leafIndex = integer(value.leaf_index, "leaf_index");
+                        if (oldRoot !== expectedRoot || leafIndex !== BigInt(leaves.length))
+                            fail("POOL_TRANSITION_INVALID", "deposit event does not continue the pinned pool history");
+                        deposits++;
+                        if (tx.transaction?.sender)
+                            depositingAddresses.add(tx.transaction.sender.toLowerCase());
+                        leaves.push(BigInt(`0x${hexVector(value.note_commitment, "note_commitment")}`));
+                        leafTransactions.push(tx.digest);
+                        expectedRoot = BigInt(`0x${hexVector(value.new_root, "new_root")}`);
+                        touched = true;
+                    }
+                    else if (name === "TransferEvent") {
+                        const oldRoot = BigInt(`0x${hexVector(value.old_root, "old_root")}`), first = integer(value.first_leaf_index, "first_leaf_index");
+                        if (oldRoot !== expectedRoot || first !== BigInt(leaves.length))
+                            fail("POOL_TRANSITION_INVALID", "transfer event does not continue the pinned pool history");
+                        leaves.push(BigInt(`0x${hexVector(value.payment_commitment, "payment_commitment")}`), BigInt(`0x${hexVector(value.change_commitment, "change_commitment")}`));
+                        leafTransactions.push(tx.digest, tx.digest);
+                        expectedRoot = BigInt(`0x${hexVector(value.new_root, "new_root")}`);
+                        touched = true;
+                    }
+                    else if (name === "WithdrawEvent" && this.moduleName === "pool_v2") {
+                        exits++;
+                        const oldRoot = BigInt(`0x${hexVector(value.old_root, "old_root")}`), leafIndex = integer(value.leaf_index, "leaf_index");
+                        if (oldRoot !== expectedRoot || leafIndex !== BigInt(leaves.length))
+                            fail("POOL_TRANSITION_INVALID", "v2 withdrawal event does not continue the pinned pool history");
+                        leaves.push(BigInt(`0x${hexVector(value.change_commitment, "change_commitment")}`));
+                        leafTransactions.push(tx.digest);
+                        expectedRoot = BigInt(`0x${hexVector(value.new_root, "new_root")}`);
+                        touched = true;
+                    }
+                    else if (name === "WithdrawEvent") {
+                        exits++;
+                        touched = true;
+                    }
+                }
+                if (touched) {
+                    checkpoint = BigInt(tx.checkpoint);
+                    transactions.push(tx.digest);
+                }
+            }
+            cursor = page.hasNextPage ? page.endCursor : null;
+            if (page.hasNextPage && !cursor)
+                fail("CHAIN_PAGINATION_INVALID", "pool history has another page without a cursor");
+        } while (cursor);
+        const computed = this.engine.tree(leaves).root;
+        if (computed !== expectedRoot)
+            fail("POOL_STATE_MISMATCH", "event leaves do not reproduce the event root");
+        const object = (await this.client.getObject({ objectId: this.poolId, include: { json: true } })).object;
+        const state = object.json;
+        if (!state || typeof state !== "object")
+            fail("POOL_STATE_MISMATCH", "pool object has no JSON state");
+        const poolState = state;
+        const chainRoot = BigInt(`0x${hexVector(poolState.root, "pool.root")}`), chainIndex = integer(poolState.next_leaf, "pool.next_leaf");
+        if (chainRoot !== computed || chainIndex !== BigInt(leaves.length))
+            fail("POOL_STATE_MISMATCH", "event-derived tree differs from the live pool object");
+        this.store.db.exec("BEGIN IMMEDIATE");
+        try {
+            this.store.db.exec("DELETE FROM live_pool_leaves");
+            const insert = this.store.db.prepare("INSERT INTO live_pool_leaves(leaf_index,commitment,transaction_digest) VALUES(?,?,?)");
+            leaves.forEach((leaf, index) => insert.run(String(index), leaf.toString(16).padStart(64, "0"), leafTransactions[index] ?? "deployment"));
+            this.store.db.prepare("INSERT INTO live_pool_sync(singleton,root,next_leaf,checkpoint,synced_at) VALUES(1,?,?,?,?) ON CONFLICT(singleton) DO UPDATE SET root=excluded.root,next_leaf=excluded.next_leaf,checkpoint=excluded.checkpoint,synced_at=excluded.synced_at").run(computed.toString(16).padStart(64, "0"), String(leaves.length), String(checkpoint), Date.now());
+            this.store.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.store.db.exec("ROLLBACK");
+            throw error;
+        }
+        return { leaves, root: computed, nextLeaf: BigInt(leaves.length), lastCheckpoint: checkpoint, transactions,
+            activity: { deposits, exits, distinctDepositingAddresses: depositingAddresses.size, reducedPrivacy: depositingAddresses.size < 5 } };
+    }
+}

package/dist/live-runtime.d.ts

@@ -0,0 +1,82 @@
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { LivePoolIndex } from "./live-index.js";
+import { ProtocolEngine } from "./protocol-engine.js";
+import { Groth16Prover, type ProverConfig } from "./prover.js";
+import { type QueuedExit } from "./v2-exits.js";
+import { TatumLedger } from "./tatum.js";
+import type { RoleStore } from "./store.js";
+export interface LiveRuntimeProfile {
+    role: "buyer" | "seller" | "auditor";
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    verifierVersion: number;
+    live: {
+        coinTypeHash: string;
+        deploymentDomain: string;
+        initialRoot: string;
+        deploymentCheckpoint: string;
+        writeGrpcEndpoint: string;
+        tatumGrpcEndpoint: string;
+        artifactRoot: string;
+        snarkjsPath: string;
+        converterPath: string;
+        rapidsnarkPath?: string;
+        artifacts: ProverConfig["expected"];
+        walrusPublisherUrl?: string;
+        walrusAggregatorUrl?: string;
+    };
+    policy: {
+        maxAmount: string;
+        allowedAssets: string[];
+        allowedCounterparties: string[];
+        requiredPrivacy: "any" | "shielded";
+        expiresAt: number;
+    };
+}
+export declare class LiveRuntime {
+    readonly profile: LiveRuntimeProfile;
+    readonly store: RoleStore;
+    readonly tatum: TatumLedger;
+    readonly signer: Ed25519Keypair;
+    readonly client: import("@mysten/sui/grpc").SuiGrpcClient;
+    readonly engine: ProtocolEngine;
+    readonly index: LivePoolIndex;
+    readonly prover: Groth16Prover;
+    private constructor();
+    static create(profile: LiveRuntimeProfile, store: RoleStore): Promise<LiveRuntime>;
+    doctor(): Promise<Record<string, unknown>>;
+    balance(): Promise<Record<string, unknown>>;
+    private signed;
+    private operationContext;
+    private existingSigned;
+    private submit;
+    private confirmTatum;
+    private prepareOpening;
+    deposit(amount: bigint, operationId: string): Promise<Record<string, unknown>>;
+    recover(): Promise<Record<string, unknown>>;
+    withdraw(commitment: string, recipient: string, operationId: string): Promise<Record<string, unknown>>;
+    queueV2Exit(commitment: string, operationId: string, amount: bigint, exactExit: boolean, windowStart: number, windowEnd: number, ownerApproved: boolean): Promise<QueuedExit>;
+    refreshV2Exit(operationId: string): Promise<{
+        refreshed: boolean;
+        requestOperationId: string;
+    }>;
+    finalizeV2Exit(operationId: string, digest: string, relayerAddress: string): Promise<Record<string, unknown>>;
+    acceptAgreement(sessionId: string, encoded: string): Record<string, unknown>;
+    prepareSellerAgreement(sessionId: string, encoded: string): Record<string, unknown>;
+    settleShielded(sessionId: string, operationId: string, bind?: (actual: {
+        amount: string;
+        counterparty: string;
+        asset: string;
+        requestId: string;
+        session: string;
+    }) => void): Promise<Record<string, unknown>>;
+    payX402Resource(operationId: string, resourceUrl: string, bind?: (actual: {
+        amount: string;
+        counterparty: string;
+        asset: string;
+        endpoint: string;
+        requestId: string;
+        requirementsHash: string;
+    }) => void): Promise<Record<string, unknown>>;
+}