@supercuts-walrus/backend 0.0.0-stage → 0.1.1

package/dist/v2-exit-worker.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/v2-exit-worker.js

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { loadStateKey } from "./config.js";
+import { Phase3App } from "./phase3.js";
+import { LiveRuntime } from "./live-runtime.js";
+import { RoleStore } from "./store.js";
+import { V2ExitQueue } from "./v2-exits.js";
+import { V2ExitRelayer } from "./v2-exit-relayer.js";
+const args = new Map();
+for (let index = 2; index < process.argv.length; index += 2) {
+    const name = process.argv[index], value = process.argv[index + 1];
+    if (!name?.startsWith("--") || !value)
+        throw Error("expected --name value arguments");
+    args.set(name.slice(2), value);
+}
+const required = (name) => args.get(name) ?? (() => { throw Error(`--${name} is required`); })();
+const sellerHome = resolve(required("seller-home")), relayerHome = resolve(required("relayer-home"));
+const pin = JSON.parse(readFileSync(resolve(required("config")), "utf8"));
+const operationId = required("operation-id"), evidencePath = resolve(required("evidence-file"));
+const pause = (milliseconds) => new Promise((done) => setTimeout(done, milliseconds));
+function requestFromStore(app) {
+    const encoded = app.store.getSecret(`v2-exit-request:${operationId}`);
+    if (!encoded)
+        throw Error("queued exit request is unavailable in the seller store");
+    const raw = JSON.parse(encoded.toString());
+    const bytes32 = (name) => Buffer.from(String(raw[name] ?? "").replace(/^0x/, ""), "hex");
+    return { operationId: String(raw.operationId), root: bytes32("root"), noteNullifier: bytes32("noteNullifier"),
+        recipient: String(raw.recipient), amount: BigInt(String(raw.amount)), exactExit: raw.exactExit === true,
+        changeCommitment: bytes32("changeCommitment"), newRoot: bytes32("newRoot"), newIndex: BigInt(String(raw.newIndex)),
+        proof: Buffer.from(String(raw.proof), "base64") };
+}
+async function attempt() {
+    if (existsSync(evidencePath))
+        return true;
+    const seller = new Phase3App(sellerHome);
+    const relayerStore = new RoleStore(join(relayerHome, "state.sqlite"), loadStateKey(join(relayerHome, "state.key")));
+    try {
+        const queue = new V2ExitQueue(seller.store), scheduled = queue.get(operationId);
+        if (!scheduled)
+            throw Error("queued exit does not exist");
+        if (scheduled.status === "queued")
+            queue.assertDue(operationId);
+        else if (scheduled.status !== "finalized")
+            throw Error("exit is awaiting an unresolved submission");
+        if (!seller.profile.live)
+            throw Error("seller profile has no live Testnet deployment");
+        const relayer = new V2ExitRelayer(relayerStore, pin), runtime = await LiveRuntime.create(seller.profile, seller.store);
+        let request = requestFromStore(seller);
+        const existing = relayerStore.db.prepare("SELECT digest FROM v2_relay_journal WHERE operation_id=?").get(request.operationId);
+        if (!existing) {
+            const state = await runtime.index.sync();
+            if (Buffer.from(request.root).toString("hex") !== state.root.toString(16).padStart(64, "0")) {
+                await runtime.refreshV2Exit(operationId);
+                request = requestFromStore(seller);
+            }
+        }
+        const relayed = await relayer.submit(request);
+        const parameters = { "exit-id": operationId, digest: relayed.digest };
+        const token = seller.approve(seller.preview("wallet.exit.finalize", parameters).challengeId);
+        const finalized = (await seller.execute("wallet.exit.finalize", { ...parameters, "approval-token": token.token })).data;
+        const evidence = { schema: "supercuts.v2.exit-completion.v1", operationId, relayer: relayed.relayer, digest: relayed.digest,
+            checkpoint: relayed.checkpoint, payoutAddress: scheduled.payoutAddress, amount: scheduled.amount.toString(),
+            exactExit: scheduled.exactExit, tatumVerified: finalized.tatumVerified, finalized: finalized.finalized, completedAt: new Date().toISOString() };
+        const temporary = `${evidencePath}.tmp`;
+        writeFileSync(temporary, `${JSON.stringify(evidence, null, 2)}\n`, { mode: 0o600 });
+        renameSync(temporary, evidencePath);
+        process.stdout.write(`${JSON.stringify(evidence)}\n`);
+        return true;
+    }
+    finally {
+        relayerStore.close();
+        seller.close();
+    }
+}
+const window = new Phase3App(sellerHome);
+let windowEnd;
+try {
+    windowEnd = new V2ExitQueue(window.store).get(operationId)?.windowEnd ?? 0;
+}
+finally {
+    window.close();
+}
+if (!windowEnd)
+    throw Error("queued exit does not exist");
+while (Date.now() < windowEnd) {
+    try {
+        if (await attempt())
+            process.exit(0);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "unknown error";
+        process.stderr.write(`${JSON.stringify({ operationId, error: message, at: new Date().toISOString() })}\n`);
+    }
+    await pause(Math.min(20_000, Math.max(1_000, windowEnd - Date.now())));
+}
+throw Error("approved exit window closed before finality was recorded");

package/dist/v2-exits.d.ts

@@ -0,0 +1,30 @@
+import type { RoleStore } from "./store.js";
+export interface QueuedExit {
+    operationId: string;
+    commitment: string;
+    payoutAddress: string;
+    amount: bigint;
+    exactExit: boolean;
+    windowStart: number;
+    executeAt: number;
+    windowEnd: number;
+    status: "queued" | "submitted" | "finalized";
+}
+/** Owner-side queue. Only the address and proof are sent to a separate relayer. */
+export declare class V2ExitQueue {
+    private readonly store;
+    constructor(store: RoleStore);
+    queue(request: {
+        operationId: string;
+        commitment: string;
+        amount: bigint;
+        exactExit: boolean;
+        windowStart: number;
+        windowEnd: number;
+    }, approved: boolean, now?: number): QueuedExit;
+    get(operationId: string): QueuedExit | undefined;
+    due(now?: number): QueuedExit[];
+    assertDue(operationId: string, now?: number): QueuedExit;
+    recordSubmission(operationId: string, digest: string): void;
+    recordFinalized(operationId: string, digest: string): void;
+}

package/dist/v2-exits.js

@@ -0,0 +1,78 @@
+import { randomInt } from "node:crypto";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { fail } from "./errors.js";
+const MAX_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+/** Owner-side queue. Only the address and proof are sent to a separate relayer. */
+export class V2ExitQueue {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS v2_exit_queue (
+      operation_id TEXT PRIMARY KEY, commitment TEXT NOT NULL UNIQUE, payout_address TEXT NOT NULL UNIQUE,
+      amount TEXT NOT NULL, exact_exit INTEGER NOT NULL, window_start INTEGER NOT NULL, execute_at INTEGER NOT NULL,
+      window_end INTEGER NOT NULL, status TEXT NOT NULL, transaction_digest TEXT UNIQUE
+    )`);
+    }
+    queue(request, approved, now = Date.now()) {
+        if (!approved)
+            fail("OWNER_APPROVAL_REQUIRED", "owner approval is required to schedule a withdrawal");
+        if (!request.operationId || request.operationId.length > 256 || !/^[0-9a-f]{64}$/i.test(request.commitment))
+            fail("EXIT_REQUEST_INVALID", "operation ID or note commitment is invalid");
+        if (request.amount <= 0n || request.amount > (1n << 64n) - 1n || (!request.exactExit && request.amount !== 1000000n))
+            fail("EXIT_AMOUNT_INVALID", "standard exit must be 1,000,000 MIST; exact exit reveals its amount");
+        if (!Number.isSafeInteger(request.windowStart) || !Number.isSafeInteger(request.windowEnd) || request.windowStart < now || request.windowEnd <= request.windowStart || request.windowEnd - request.windowStart > MAX_WINDOW_MS)
+            fail("EXIT_WINDOW_INVALID", "exit window must be in the future and no longer than seven days");
+        const prior = this.get(request.operationId);
+        if (prior) {
+            if (prior.commitment !== request.commitment || prior.amount !== request.amount || prior.exactExit !== request.exactExit || prior.windowStart !== request.windowStart || prior.windowEnd !== request.windowEnd)
+                fail("OPERATION_ID_CONFLICT", "exit operation ID is already bound to another request");
+            return prior;
+        }
+        // Node's randomInt uses a cryptographic random source and avoids modulo bias.
+        const executeAt = randomInt(request.windowStart, request.windowEnd);
+        const payout = Ed25519Keypair.generate();
+        const payoutAddress = payout.toSuiAddress();
+        this.store.db.exec("BEGIN IMMEDIATE");
+        try {
+            this.store.putSecretOnce(`v2-exit-payout:${request.operationId}`, Buffer.from(payout.getSecretKey()));
+            this.store.db.prepare("INSERT INTO v2_exit_queue(operation_id,commitment,payout_address,amount,exact_exit,window_start,execute_at,window_end,status) VALUES(?,?,?,?,?,?,?,?,'queued')")
+                .run(request.operationId, request.commitment, payoutAddress, request.amount.toString(), Number(request.exactExit), request.windowStart, executeAt, request.windowEnd);
+            this.store.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.store.db.exec("ROLLBACK");
+            throw error;
+        }
+        return this.get(request.operationId);
+    }
+    get(operationId) {
+        const row = this.store.db.prepare("SELECT operation_id,commitment,payout_address,amount,exact_exit,window_start,execute_at,window_end,status FROM v2_exit_queue WHERE operation_id=?").get(operationId);
+        return row && { operationId: row.operation_id, commitment: row.commitment, payoutAddress: row.payout_address, amount: BigInt(row.amount), exactExit: Boolean(row.exact_exit), windowStart: row.window_start, executeAt: row.execute_at, windowEnd: row.window_end, status: row.status };
+    }
+    due(now = Date.now()) {
+        const rows = this.store.db.prepare("SELECT operation_id FROM v2_exit_queue WHERE status='queued' AND execute_at<=? AND window_end>? ORDER BY execute_at").all(now, now);
+        return rows.map((row) => this.get(row.operation_id));
+    }
+    assertDue(operationId, now = Date.now()) {
+        const exit = this.get(operationId) ?? fail("OPERATION_ID_CONFLICT", "exit has no journal entry");
+        if (exit.status !== "queued" || now < exit.executeAt || now >= exit.windowEnd)
+            fail("EXIT_WINDOW_CLOSED", "exit can only be submitted inside its scheduled window");
+        return exit;
+    }
+    recordSubmission(operationId, digest) {
+        if (!/^[1-9A-HJ-NP-Za-km-z]{32,64}$/.test(digest))
+            fail("EXIT_DIGEST_INVALID", "relayer transaction digest is invalid");
+        const row = this.store.db.prepare("SELECT status,transaction_digest FROM v2_exit_queue WHERE operation_id=?").get(operationId);
+        if (!row)
+            return fail("OPERATION_ID_CONFLICT", "exit submission has no journal entry");
+        if (row.transaction_digest && row.transaction_digest !== digest)
+            fail("OPERATION_ID_CONFLICT", "exit submission conflicts with the journal");
+        this.store.db.prepare("UPDATE v2_exit_queue SET status='submitted',transaction_digest=? WHERE operation_id=? AND status='queued'").run(digest, operationId);
+    }
+    recordFinalized(operationId, digest) {
+        const row = this.store.db.prepare("SELECT transaction_digest FROM v2_exit_queue WHERE operation_id=?").get(operationId);
+        if (!row || row.transaction_digest !== digest)
+            fail("OPERATION_ID_CONFLICT", "finality does not match the journaled relayer transaction");
+        this.store.db.prepare("UPDATE v2_exit_queue SET status='finalized' WHERE operation_id=?").run(operationId);
+    }
+}

package/dist/v2-prefund.d.ts

@@ -0,0 +1,19 @@
+import type { RoleStore } from "./store.js";
+export interface PrefundPlan {
+    operationId: string;
+    amount: bigint;
+    scheduledAt: number;
+    status: "queued" | "finalized";
+    transactionDigest?: string;
+}
+/** Buyer-side scheduling; the callback must be the live, finalized deposit path. */
+export declare class V2PrefundQueue {
+    private readonly store;
+    constructor(store: RoleStore);
+    queue(operationId: string, amount: bigint, scheduledAt: number, approved: boolean, now?: number): PrefundPlan;
+    get(operationId: string): PrefundPlan | undefined;
+    runDue(now: number, deposit: (amount: bigint, operationId: string) => Promise<{
+        transactionDigest: string;
+        finalized: boolean;
+    }>): Promise<PrefundPlan[]>;
+}

package/dist/v2-prefund.js

@@ -0,0 +1,43 @@
+import { fail } from "./errors.js";
+/** Buyer-side scheduling; the callback must be the live, finalized deposit path. */
+export class V2PrefundQueue {
+    store;
+    constructor(store) {
+        this.store = store;
+        store.db.exec(`CREATE TABLE IF NOT EXISTS v2_prefund_queue (
+      operation_id TEXT PRIMARY KEY, amount TEXT NOT NULL, scheduled_at INTEGER NOT NULL,
+      status TEXT NOT NULL, transaction_digest TEXT UNIQUE
+    )`);
+    }
+    queue(operationId, amount, scheduledAt, approved, now = Date.now()) {
+        if (!approved)
+            fail("OWNER_APPROVAL_REQUIRED", "owner approval is required to schedule prefunding");
+        if (!operationId || operationId.length > 256 || (amount !== 10000000n && amount !== 100000000n) || !Number.isSafeInteger(scheduledAt) || scheduledAt < now)
+            fail("PREFUND_PLAN_INVALID", "v2 prefunding needs a standard amount and future time");
+        const prior = this.get(operationId);
+        if (prior) {
+            if (prior.amount !== amount || prior.scheduledAt !== scheduledAt)
+                fail("OPERATION_ID_CONFLICT", "prefunding operation ID identifies another plan");
+            return prior;
+        }
+        this.store.db.prepare("INSERT INTO v2_prefund_queue(operation_id,amount,scheduled_at,status) VALUES(?,?,?,'queued')").run(operationId, amount.toString(), scheduledAt);
+        return this.get(operationId);
+    }
+    get(operationId) {
+        const row = this.store.db.prepare("SELECT operation_id,amount,scheduled_at,status,transaction_digest FROM v2_prefund_queue WHERE operation_id=?").get(operationId);
+        return row && { operationId: row.operation_id, amount: BigInt(row.amount), scheduledAt: row.scheduled_at, status: row.status, ...(row.transaction_digest ? { transactionDigest: row.transaction_digest } : {}) };
+    }
+    async runDue(now, deposit) {
+        const rows = this.store.db.prepare("SELECT operation_id FROM v2_prefund_queue WHERE status='queued' AND scheduled_at<=? ORDER BY scheduled_at").all(now);
+        const finalized = [];
+        for (const row of rows) {
+            const plan = this.get(row.operation_id);
+            const receipt = await deposit(plan.amount, plan.operationId);
+            if (!receipt.finalized || !receipt.transactionDigest)
+                fail("PREFUND_NOT_FINAL", "prefunding callback did not return a finalized live deposit");
+            this.store.db.prepare("UPDATE v2_prefund_queue SET status='finalized',transaction_digest=? WHERE operation_id=? AND status='queued'").run(receipt.transactionDigest, plan.operationId);
+            finalized.push(this.get(plan.operationId));
+        }
+        return finalized;
+    }
+}

package/dist/v2-relayer-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/v2-relayer-cli.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+import { readFileSync, statSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { loadStateKey } from "./config.js";
+import { RoleStore } from "./store.js";
+import { V2ExitRelayer } from "./v2-exit-relayer.js";
+const [command, ...words] = process.argv.slice(2);
+const args = new Map();
+for (let index = 0; index < words.length; index += 2) {
+    if (!words[index]?.startsWith("--") || !words[index + 1])
+        throw Error("expected --name value arguments");
+    args.set(words[index].slice(2), words[index + 1]);
+}
+const required = (name) => args.get(name) ?? (() => { throw Error(`--${name} is required`); })();
+const stateDir = resolve(required("state-dir"));
+const config = JSON.parse(readFileSync(resolve(required("config")), "utf8"));
+const store = new RoleStore(join(stateDir, "state.sqlite"), loadStateKey(join(stateDir, "state.key")));
+try {
+    const relayer = new V2ExitRelayer(store, config);
+    if (command === "doctor")
+        console.log(JSON.stringify(await relayer.doctor()));
+    else if (command === "submit") {
+        const requestPath = resolve(required("request-file"));
+        if ((statSync(requestPath).mode & 0o077) !== 0)
+            throw Error("request file must be owner-only");
+        const raw = JSON.parse(readFileSync(requestPath, "utf8"));
+        const bytes32 = (name) => Buffer.from(String(raw[name] ?? "").replace(/^0x/, ""), "hex");
+        const result = await relayer.submit({ operationId: String(raw.operationId), root: bytes32("root"), noteNullifier: bytes32("noteNullifier"),
+            recipient: String(raw.recipient), amount: BigInt(String(raw.amount)), exactExit: raw.exactExit === true,
+            changeCommitment: bytes32("changeCommitment"), newRoot: bytes32("newRoot"), newIndex: BigInt(String(raw.newIndex)),
+            proof: Buffer.from(String(raw.proof), "base64") });
+        console.log(JSON.stringify(result));
+    }
+    else
+        throw Error("use doctor or submit");
+}
+finally {
+    store.close();
+}

package/dist/wallet.d.ts

@@ -0,0 +1,32 @@
+import { PoolEvent } from "./indexer.js";
+import { RoleStore, StoredOperation } from "./store.js";
+import { NoteOpening } from "./notes.js";
+export interface SettlementEvidence {
+    digest: string;
+    finalized: boolean;
+    successful: boolean;
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    events: PoolEvent[];
+}
+export type EvidenceReader = (digest: string) => Promise<SettlementEvidence | undefined>;
+export interface SettlementExpectation {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    inputNullifier: string;
+    dealNullifier: string;
+    paymentCommitment: string;
+    changeCommitment: string;
+}
+export declare class PrivateWallet {
+    private readonly store;
+    constructor(store: RoleStore);
+    prepare(operationId: string, payloadHash: string, inputCommitment: string, expected: SettlementExpectation, proof: Uint8Array): void;
+    recordBroadcast(operationId: string, digest: string): void;
+    reconcile(operationId: string, read: EvidenceReader): Promise<StoredOperation>;
+    recoverOutput(operationId: string, role: "payment" | "change", opening: NoteOpening, event: Extract<PoolEvent, {
+        kind: "transfer";
+    }>): Promise<string>;
+}

package/dist/wallet.js

@@ -0,0 +1,90 @@
+import { fail } from "./errors.js";
+import { encodeNoteOpening, noteCommitment } from "./notes.js";
+function encodeExpectation(expected) {
+    const entries = Object.entries(expected);
+    if (entries.some(([, value]) => !value || typeof value !== "string" || value.length > 512))
+        fail("SETTLEMENT_EXPECTATION_INVALID", "settlement expectation is incomplete or too large");
+    return Buffer.from(JSON.stringify(Object.fromEntries(entries.sort(([a], [b]) => a.localeCompare(b)))));
+}
+function rejectEvidence(store, operationId, code, message) {
+    const status = store.getOperation(operationId)?.status;
+    if (status && status !== "unresolved" && status !== "finalized" && status !== "confirmed" && status !== "delivered")
+        store.transitionOperation(operationId, "unresolved");
+    return fail(code, message);
+}
+export class PrivateWallet {
+    store;
+    constructor(store) {
+        this.store = store;
+    }
+    prepare(operationId, payloadHash, inputCommitment, expected, proof) {
+        this.store.beginOperation(operationId, payloadHash);
+        this.store.reserveNote(inputCommitment, operationId);
+        this.store.putSecretOnce(`settlement:${operationId}`, encodeExpectation(expected));
+        this.store.putNote(inputCommitment, "input", operationId, undefined, expected.inputNullifier);
+        const operation = this.store.getOperation(operationId);
+        if (operation.status === "reserved") {
+            this.store.putSecretOnce(`proof:${operationId}`, proof);
+            this.store.transitionOperation(operationId, "proof_persisted");
+        }
+        else if (!this.store.getSecret(`proof:${operationId}`)?.equals(Buffer.from(proof))) {
+            fail("PROOF_RETRY_CONFLICT", "retry proof differs from the persisted proof");
+        }
+    }
+    recordBroadcast(operationId, digest) {
+        const operation = this.store.getOperation(operationId) ?? fail("OPERATION_NOT_FOUND", `operation ${operationId} does not exist`);
+        if (operation.txDigest && operation.txDigest !== digest)
+            fail("OPERATION_DIGEST_CONFLICT", "operation cannot be rebound to another transaction");
+        if (operation.status === "proof_persisted" || (operation.status === "unresolved" && this.store.getSecret(`proof:${operationId}`)))
+            this.store.transitionOperation(operationId, "broadcast", digest);
+        else if (operation.status !== "broadcast" && operation.status !== "finalized" && operation.status !== "confirmed" && operation.status !== "delivered")
+            fail("OPERATION_NOT_READY", "proof must be persisted before broadcast");
+    }
+    async reconcile(operationId, read) {
+        const operation = this.store.getOperation(operationId) ?? fail("OPERATION_NOT_FOUND", `operation ${operationId} does not exist`);
+        const encodedExpectation = this.store.getSecret(`settlement:${operationId}`) ?? fail("SETTLEMENT_EXPECTATION_MISSING", "operation has no persisted settlement expectation");
+        let expected;
+        try {
+            expected = JSON.parse(encodedExpectation.toString());
+        }
+        catch (error) {
+            return fail("SETTLEMENT_EXPECTATION_INVALID", "persisted settlement expectation is invalid", error);
+        }
+        if (!operation.txDigest)
+            return operation;
+        const evidence = await read(operation.txDigest);
+        if (!evidence || !evidence.finalized) {
+            if (operation.status !== "unresolved")
+                this.store.transitionOperation(operationId, "unresolved");
+            return this.store.getOperation(operationId);
+        }
+        if (evidence.digest !== operation.txDigest)
+            rejectEvidence(this.store, operationId, "SETTLEMENT_DIGEST_MISMATCH", "evidence reader returned another transaction");
+        if (!evidence.successful)
+            rejectEvidence(this.store, operationId, "SETTLEMENT_FAILED", "finalized transaction did not execute successfully");
+        if (evidence.packageId !== expected.packageId || evidence.poolId !== expected.poolId || evidence.coinType !== expected.coinType)
+            rejectEvidence(this.store, operationId, "SETTLEMENT_TARGET_MISMATCH", "transaction does not settle against the pinned pool and asset");
+        const transfer = evidence.events.find((event) => event.kind === "transfer" && event.inputNullifier === expected.inputNullifier && event.dealNullifier === expected.dealNullifier && event.paymentCommitment === expected.paymentCommitment && event.changeCommitment === expected.changeCommitment);
+        if (!transfer)
+            rejectEvidence(this.store, operationId, "SETTLEMENT_EVENT_MISSING", "finalized transaction does not contain the expected transfer");
+        if (operation.status === "broadcast" || operation.status === "unresolved")
+            this.store.transitionOperation(operationId, "finalized", evidence.digest);
+        this.store.markNoteSpent(expected.inputNullifier);
+        return this.store.getOperation(operationId);
+    }
+    async recoverOutput(operationId, role, opening, event) {
+        const operation = this.store.getOperation(operationId) ?? fail("OPERATION_NOT_FOUND", `operation ${operationId} does not exist`);
+        if (!["finalized", "confirmed", "delivered"].includes(operation.status))
+            fail("NOTE_RECOVERY_NOT_FINAL", "output notes can only be recovered from a finalized operation");
+        const expected = JSON.parse((this.store.getSecret(`settlement:${operationId}`) ?? fail("SETTLEMENT_EXPECTATION_MISSING", "operation has no persisted settlement expectation")).toString());
+        if (event.inputNullifier !== expected.inputNullifier || event.dealNullifier !== expected.dealNullifier || event.paymentCommitment !== expected.paymentCommitment || event.changeCommitment !== expected.changeCommitment)
+            fail("NOTE_RECOVERY_EVENT_MISMATCH", "recovery event does not match the persisted settlement");
+        const commitment = await noteCommitment(opening);
+        const expectedCommitment = role === "payment" ? event.paymentCommitment : event.changeCommitment;
+        if (commitment !== expectedCommitment)
+            fail("NOTE_RECOVERY_MISMATCH", `${role} opening does not match the finalized commitment`);
+        this.store.putSecretOnce(`note:${commitment}`, encodeNoteOpening(opening));
+        this.store.putNote(commitment, role, operationId, event.firstLeafIndex + (role === "change" ? 1n : 0n));
+        return commitment;
+    }
+}

package/dist/workflow-memory.d.ts

@@ -0,0 +1,22 @@
+import { MemoryFact, RailPolicy } from "./memory.js";
+import { RoleStore } from "./store.js";
+export interface MemoryWriter {
+    remember(fact: MemoryFact): Promise<string>;
+}
+export interface RecalledRule {
+    hiddenAmountRequired?: boolean;
+    seller?: string;
+    maxAmount?: bigint;
+}
+export declare class WorkflowMemory {
+    private readonly store;
+    private readonly memory;
+    constructor(store: RoleStore, memory: MemoryWriter);
+    record(fact: MemoryFact): Promise<string>;
+    completed(): Array<{
+        operationId: string;
+        blobId: string;
+    }>;
+}
+export declare function policyFromRecall(rules: RecalledRule[]): RailPolicy;
+export declare function decideRailFromRecall(rules: RecalledRule[], requested: "shielded" | "x402"): "shielded" | "x402";

package/dist/workflow-memory.js

@@ -0,0 +1,49 @@
+import { createHash } from "node:crypto";
+import { fail } from "./errors.js";
+import { selectRail, validateMemoryFact } from "./memory.js";
+export class WorkflowMemory {
+    store;
+    memory;
+    constructor(store, memory) {
+        this.store = store;
+        this.memory = memory;
+    }
+    async record(fact) {
+        validateMemoryFact(fact);
+        const factHash = createHash("sha256").update(JSON.stringify({ kind: fact.kind, subject: fact.subject, observation: fact.observation, operationId: fact.operationId, createdAt: fact.createdAt })).digest("hex");
+        const existing = this.store.db.prepare("SELECT fact_hash, blob_id, status FROM memory_jobs WHERE operation_id = ?").get(fact.operationId);
+        if (existing && existing.fact_hash !== factHash)
+            fail("MEMORY_OPERATION_CONFLICT", "memory operation ID already identifies another fact");
+        if (existing?.status === "complete" && existing.blob_id)
+            return existing.blob_id;
+        if (existing)
+            fail(existing.status === "unresolved" ? "MEMORY_JOB_UNRESOLVED" : "MEMORY_JOB_PENDING", "memory write cannot be repeated without reconciling its prior job");
+        const inserted = this.store.db.prepare("INSERT OR IGNORE INTO memory_jobs(operation_id, kind, fact_hash, blob_id, status, created_at) VALUES (?, ?, ?, NULL, 'pending', ?)").run(fact.operationId, fact.kind, factHash, Date.now());
+        if (inserted.changes !== 1)
+            fail("MEMORY_JOB_PENDING", "another process started this memory write");
+        try {
+            const blobId = await this.memory.remember(fact);
+            if (!blobId)
+                fail("MEMORY_BLOB_MISSING", "completed memory write returned no blob ID");
+            this.store.db.prepare("UPDATE memory_jobs SET blob_id = ?, status = 'complete' WHERE operation_id = ? AND status = 'pending'").run(blobId, fact.operationId);
+            return blobId;
+        }
+        catch (error) {
+            this.store.db.prepare("UPDATE memory_jobs SET status = 'unresolved' WHERE operation_id = ? AND status = 'pending'").run(fact.operationId);
+            throw error;
+        }
+    }
+    completed() {
+        return this.store.db.prepare("SELECT operation_id, blob_id FROM memory_jobs WHERE status = 'complete' ORDER BY created_at").all()
+            .map((row) => { const value = row; return { operationId: value.operation_id, blobId: value.blob_id }; });
+    }
+}
+export function policyFromRecall(rules) {
+    if (!rules.length)
+        return { hiddenAmountRequired: false, recalledRulesAvailable: false, contradictory: false };
+    const privacy = rules.map((rule) => rule.hiddenAmountRequired).filter((value) => value !== undefined);
+    return { hiddenAmountRequired: privacy.includes(true), recalledRulesAvailable: true, contradictory: privacy.includes(true) && privacy.includes(false) };
+}
+export function decideRailFromRecall(rules, requested) {
+    return selectRail(policyFromRecall(rules), requested);
+}

package/dist/x402-resource-service.d.ts

@@ -0,0 +1,36 @@
+import { type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { RoleStore } from "./store.js";
+export interface X402ResourceServiceConfig {
+    origin: string;
+    pathPrefix?: string;
+    facilitatorUrl: string;
+    /** Owner-only credential for the facilitator. Never put this in a manifest or buyer profile. */
+    facilitatorKey: string;
+    network: "sui:testnet";
+    asset: string;
+    payTo: string;
+    amount: string;
+    maxTimeoutSeconds?: number;
+    /** Bounded retry schedule for transient facilitator cold starts. */
+    facilitatorRetryDelaysMs?: number[];
+}
+/** Seller-owned standard x402 v2 exact resource with additional request-binding replay protection. */
+export declare class X402ResourceService {
+    #private;
+    readonly config: X402ResourceServiceConfig;
+    private readonly http;
+    private readonly persist?;
+    private readonly claimExternal?;
+    constructor(store: RoleStore, config: X402ResourceServiceConfig, http?: typeof fetch, persist?: (() => Promise<void>) | undefined, claimExternal?: ((digest: string, requestId: string) => Promise<void>) | undefined);
+    register(requestId: string, operationId: string, body: Uint8Array): {
+        url: string;
+        artifactSha256: string;
+    };
+    private requirements;
+    private resourceUrl;
+    private challenge;
+    handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+    createServer(): Server;
+    private facilitator;
+    private send;
+}