@supercuts-walrus/backend 0.0.0-stage → 0.1.0

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,34 @@
+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;
+}
+/** 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;
+}

package/dist/x402-resource-service.js

@@ -0,0 +1,154 @@
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { fail, SupercutsError } from "./errors.js";
+import { paymentBindingBytes, PaymentConsumptionLedger, requirementsHash, verifyBinding, verifyExactPayment } from "./x402.js";
+import { isValidPersonalMessageSignature } from "@mysten/sui/verify";
+const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64");
+function decode(value, code) {
+    const encoded = value ?? fail(code, "required x402 header is missing");
+    try {
+        const parsed = JSON.parse(Buffer.from(encoded, "base64").toString());
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            fail(code, "x402 header must encode an object");
+        return parsed;
+    }
+    catch (error) {
+        return fail(code, "x402 header is not valid base64 JSON", error);
+    }
+}
+function safeUrl(value) { try {
+    return new URL(value);
+}
+catch (error) {
+    return fail("X402_CONFIG_INVALID", "x402 service URL is invalid", error);
+} }
+/** Seller-owned standard x402 v2 exact resource with additional request-binding replay protection. */
+export class X402ResourceService {
+    config;
+    http;
+    persist;
+    claimExternal;
+    #ledger;
+    #artifacts = new Map();
+    #origin;
+    #facilitator;
+    #prefix;
+    constructor(store, config, http = fetch, persist, claimExternal) {
+        this.config = config;
+        this.http = http;
+        this.persist = persist;
+        this.claimExternal = claimExternal;
+        this.#ledger = new PaymentConsumptionLedger(store);
+        this.#origin = safeUrl(config.origin);
+        this.#facilitator = safeUrl(config.facilitatorUrl);
+        this.#prefix = (config.pathPrefix ?? "/capability").replace(/\/$/, "");
+        if (this.#origin.protocol !== "https:" && !(this.#origin.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(this.#origin.hostname)))
+            fail("X402_CONFIG_INVALID", "resource origin must use HTTPS except on loopback");
+        if (this.#facilitator.protocol !== "https:" && !(this.#facilitator.protocol === "http:" && ["localhost", "127.0.0.1", "::1"].includes(this.#facilitator.hostname)))
+            fail("X402_CONFIG_INVALID", "facilitator must use HTTPS except on loopback");
+        if (!/^0x[0-9a-f]{64}$/i.test(config.payTo) || !/^0x[0-9a-f]+::[A-Za-z0-9_]+::[A-Za-z0-9_]+$/.test(config.asset) || !/^[1-9][0-9]*$/.test(config.amount))
+            fail("X402_CONFIG_INVALID", "payTo, asset, or amount is invalid");
+        if (!config.facilitatorKey || config.facilitatorKey.length < 24 || config.facilitatorKey.length > 1024)
+            fail("X402_CONFIG_INVALID", "facilitatorKey must be an owner-only secret");
+    }
+    register(requestId, operationId, body) {
+        if (!requestId || !operationId || requestId.length > 256 || operationId.length > 256 || !body.length || body.length > 10 * 1024 * 1024)
+            fail("RESOURCE_INVALID", "artifact registration is invalid");
+        const existing = this.#artifacts.get(requestId), next = Buffer.from(body);
+        if (existing && (existing.operationId !== operationId || !existing.body.equals(next)))
+            fail("RESOURCE_REQUEST_CONFLICT", "request already identifies another artifact or operation");
+        this.#artifacts.set(requestId, { requestId, operationId, body: next });
+        return { url: new URL(`${this.#prefix}/${encodeURIComponent(requestId)}`, this.#origin).toString(), artifactSha256: (awaitHash(next)) };
+    }
+    requirements(artifact) {
+        return { scheme: "exact", network: this.config.network, amount: this.config.amount, asset: this.config.asset, payTo: this.config.payTo, maxTimeoutSeconds: this.config.maxTimeoutSeconds ?? 300, extra: { requestId: artifact.requestId, operationId: artifact.operationId } };
+    }
+    resourceUrl(requestId) { return new URL(`${this.#prefix}/${encodeURIComponent(requestId)}`, this.#origin).toString(); }
+    challenge(artifact) {
+        // The live Sui exact facilitator requires the x402 nonce to be exactly
+        // 32 random bytes (hex encoded), not merely an application nonce.
+        const requirements = this.requirements(artifact), nonce = this.#ledger.challenge(artifact.requestId, requirementsHash(requirements), () => randomBytes(32).toString("hex"));
+        requirements.extra = { ...requirements.extra, nonce };
+        // The nonce changes the signed requirement set and is persisted per request.
+        const finalHash = requirementsHash(requirements);
+        return { x402Version: 2, resource: { url: this.resourceUrl(artifact.requestId), description: "Supercuts seller capability artifact", mimeType: "application/json" }, accepts: [{ ...requirements, extra: { ...requirements.extra, requirementsHash: finalHash } }] };
+    }
+    async handle(request, response) {
+        try {
+            if (request.method !== "GET")
+                return this.send(response, 405, Buffer.from("Method Not Allowed"), { allow: "GET" });
+            const url = new URL(request.url ?? "/", this.#origin), prefix = `${this.#prefix}/`;
+            if (!url.pathname.startsWith(prefix))
+                return this.send(response, 404, Buffer.from("Not Found"));
+            const requestId = decodeURIComponent(url.pathname.slice(prefix.length)), artifact = this.#artifacts.get(requestId);
+            if (!artifact)
+                return this.send(response, 404, Buffer.from("Not Found"));
+            const challenge = this.challenge(artifact), requirements = challenge.accepts instanceof Array ? challenge.accepts[0] : fail("X402_STATE_INVALID", "challenge omitted requirements");
+            const paymentHeader = Array.isArray(request.headers["payment-signature"]) ? request.headers["payment-signature"][0] : request.headers["payment-signature"];
+            if (!paymentHeader) {
+                await this.persist?.();
+                return this.send(response, 402, Buffer.from("Payment Required"), { "payment-required": encode(challenge) });
+            }
+            const stored = this.#ledger.getChallenge(artifact.requestId, requirementsHash(this.requirements(artifact))) ?? fail("X402_CHALLENGE_MISSING", "resource challenge was not persisted");
+            if (!this.#ledger.isDeliveryComplete(artifact.requestId) && Date.now() > stored.createdAt + requirements.maxTimeoutSeconds * 1_000)
+                fail("X402_CHALLENGE_EXPIRED", "payment challenge has expired");
+            const payload = decode(paymentHeader, "X402_PAYMENT_INVALID"), bindingValue = Array.isArray(request.headers["x-supercuts-binding"]) ? request.headers["x-supercuts-binding"][0] : request.headers["x-supercuts-binding"], binding = decode(bindingValue, "X402_REQUEST_BINDING_INVALID");
+            const offered = payload.accepted;
+            if (!offered || requirementsHash(offered) !== requirementsHash(requirements))
+                fail("X402_REQUIREMENTS_MISMATCH", "payment payload changed the challenged requirements");
+            const extra = requirements.extra, nonce = String(extra.nonce ?? ""), declaredHash = String(extra.requirementsHash ?? "");
+            const unsignedRequirements = { ...requirements, extra: { requestId: extra.requestId, operationId: extra.operationId, nonce } };
+            if (declaredHash !== requirementsHash(unsignedRequirements))
+                fail("X402_REQUIREMENTS_MISMATCH", "challenge requirements hash is invalid");
+            verifyBinding(binding, artifact.requestId, nonce, unsignedRequirements, binding.transactionDigest);
+            const { payerSignature: _signature, ...unsignedBinding } = binding;
+            if (!(await isValidPersonalMessageSignature(paymentBindingBytes(unsignedBinding), binding.payerSignature, { address: binding.payer })))
+                fail("X402_PAYER_SIGNATURE_INVALID", "payer did not bind payment to this resource request");
+            const body = { x402Version: 2, paymentPayload: payload, paymentRequirements: requirements };
+            const verified = await this.facilitator("verify", body);
+            if (verified.isValid !== true)
+                fail("X402_FACILITATOR_REJECTED", "facilitator rejected the signed payment");
+            const settled = await this.facilitator("settle", body), digest = String(settled.transaction ?? "");
+            if (settled.success !== true || settled.network !== this.config.network || digest !== binding.transactionDigest)
+                fail("X402_SETTLEMENT_INVALID", "facilitator returned mismatched settlement evidence");
+            const payment = { digest, network: this.config.network, asset: this.config.asset, amount: BigInt(this.config.amount), payTo: this.config.payTo, finalized: true };
+            verifyExactPayment(payment, requirements);
+            await this.claimExternal?.(digest, artifact.requestId);
+            this.#ledger.claim(payment, artifact.requestId);
+            let delivery = this.#ledger.getDelivery(artifact.requestId);
+            if (!this.#ledger.isDeliveryComplete(artifact.requestId)) {
+                if (!this.#ledger.acquireDelivery(artifact.requestId))
+                    fail("DELIVERY_IN_PROGRESS", "resource delivery is already being produced");
+                this.#ledger.completeDelivery(artifact.requestId, artifact.body);
+                delivery = artifact.body;
+            }
+            await this.persist?.();
+            return this.send(response, 200, delivery ?? fail("DELIVERY_STATE_INVALID", "completed delivery has no bytes"), { "content-type": "application/json", "payment-response": encode({ success: true, transaction: digest, network: this.config.network }) });
+        }
+        catch (error) {
+            const known = error instanceof SupercutsError ? error : new SupercutsError("INTERNAL_ERROR", "resource service failed");
+            return this.send(response, known.code === "PAYMENT_CONSUMED" ? 409 : 400, Buffer.from(JSON.stringify({ error: known.code, message: known.message })), { "content-type": "application/json" });
+        }
+    }
+    createServer() { return createServer((request, response) => void this.handle(request, response)); }
+    async facilitator(path, body) {
+        const endpoint = new URL(path, `${this.#facilitator.toString().replace(/\/$/, "")}/`);
+        const response = await this.http(endpoint, { method: "POST", headers: { "content-type": "application/json", "x-supercuts-facilitator-key": this.config.facilitatorKey }, body: JSON.stringify(body), signal: AbortSignal.timeout(60_000) });
+        let value;
+        try {
+            value = await response.json();
+        }
+        catch (error) {
+            return fail("X402_FACILITATOR_INVALID", "facilitator returned invalid JSON", error);
+        }
+        if (!response.ok || !value || typeof value !== "object" || Array.isArray(value)) {
+            const message = value && typeof value === "object" && !Array.isArray(value) && typeof value.message === "string"
+                ? `: ${value.message}` : "";
+            fail("X402_FACILITATOR_INVALID", `facilitator ${path} failed with ${response.status}${message}`);
+        }
+        return value;
+    }
+    send(response, status, body, headers = {}) { response.writeHead(status, { "content-length": String(body.length), ...headers }); response.end(body); }
+}
+import { createHash } from "node:crypto";
+function awaitHash(value) { return createHash("sha256").update(value).digest("hex"); }

package/dist/x402.d.ts

@@ -0,0 +1,46 @@
+import { RoleStore } from "./store.js";
+export interface ExactRequirements {
+    scheme: "exact";
+    network: string;
+    amount: string;
+    asset: string;
+    payTo: string;
+    maxTimeoutSeconds: number;
+    extra: Record<string, unknown>;
+}
+export interface PaymentBinding {
+    requestId: string;
+    nonce: string;
+    requirementsHash: string;
+    transactionDigest: string;
+    payer: string;
+    payerSignature: string;
+}
+export interface FinalPayment {
+    digest: string;
+    network: string;
+    asset: string;
+    amount: bigint;
+    payTo: string;
+    finalized: boolean;
+}
+export declare function requirementsHash(requirements: ExactRequirements): string;
+export declare function paymentBindingBytes(binding: Omit<PaymentBinding, "payerSignature">): Uint8Array;
+export declare class PaymentConsumptionLedger {
+    private readonly store;
+    constructor(store: RoleStore);
+    claim(payment: FinalPayment, requestId: string): void;
+    recordDelivery(requestId: string, response: Uint8Array): void;
+    getDelivery(requestId: string): Buffer | undefined;
+    isDeliveryComplete(requestId: string): boolean;
+    acquireDelivery(requestId: string, now?: number, leaseMs?: number): boolean;
+    releaseDelivery(requestId: string): void;
+    completeDelivery(requestId: string, response: Uint8Array): void;
+    challenge(requestId: string, requirementsHashValue: string, createNonce: () => string): string;
+    getChallenge(requestId: string, requirementsHashValue: string): {
+        nonce: string;
+        createdAt: number;
+    } | undefined;
+}
+export declare function verifyBinding(binding: PaymentBinding, requestId: string, nonce: string, requirements: ExactRequirements, transactionDigest: string): void;
+export declare function verifyExactPayment(payment: FinalPayment, requirements: ExactRequirements): void;