@supercuts-walrus/backend 0.0.0-stage → 0.1.0

package/dist/sui.js

@@ -0,0 +1,77 @@
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { Transaction } from "@mysten/sui/transactions";
+import { fail } from "./errors.js";
+const bytes = (value) => Array.from(value);
+const validateCommon = (call) => {
+    if (!/^0x[0-9a-f]{64}$/i.test(call.packageId) || !/^0x[0-9a-f]{64}$/i.test(call.poolId) || !/^[^\s:]+(?:::[^\s:]+){2}(?:<.*>)?$/.test(call.coinType))
+        fail("POOL_ARGUMENT_INVALID", "package, pool, or coin type is invalid");
+    if (!call.proof.length || call.proof.length > 4096)
+        fail("POOL_ARGUMENT_INVALID", "proof length is invalid");
+};
+const validateU64 = (value, name, positive = false) => {
+    if (value < (positive ? 1n : 0n) || value > (1n << 64n) - 1n)
+        fail("POOL_ARGUMENT_INVALID", `${name} must be ${positive ? "a positive " : "an "}u64 value`);
+};
+const validate32 = (values) => {
+    for (const [name, value] of Object.entries(values))
+        if (value.length !== 32)
+            fail("POOL_ARGUMENT_INVALID", `${name} must contain 32 bytes`);
+};
+export function buildDeposit(call) {
+    validateCommon(call);
+    validateU64(call.amount, "amount", true);
+    validateU64(call.newIndex, "new index");
+    validate32({ noteCommitment: call.noteCommitment, newRoot: call.newRoot });
+    const tx = new Transaction();
+    const [coin] = tx.splitCoins(tx.gas, [tx.pure.u64(call.amount)]);
+    tx.moveCall({ target: `${call.packageId}::${call.poolModule ?? "pool"}::deposit`, typeArguments: [call.coinType], arguments: [
+            tx.object(call.poolId), coin, tx.pure.vector("u8", bytes(call.noteCommitment)), tx.pure.vector("u8", bytes(call.newRoot)),
+            tx.pure.u64(call.newIndex), tx.pure.vector("u8", bytes(call.proof)),
+        ] });
+    return tx;
+}
+export function buildPrivateTransfer(call) {
+    validateCommon(call);
+    validateU64(call.expiryMs, "expiry");
+    validateU64(call.newIndex, "new index");
+    validate32({ dealCommitment: call.dealCommitment, dealNullifier: call.dealNullifier, inputNullifier: call.inputNullifier, paymentCommitment: call.paymentCommitment, changeCommitment: call.changeCommitment, newRoot: call.newRoot });
+    const tx = new Transaction();
+    tx.moveCall({ target: `${call.packageId}::${call.poolModule ?? "pool"}::transfer_private`, typeArguments: [call.coinType], arguments: [
+            tx.object(call.poolId), tx.object("0x6"), tx.pure.vector("u8", bytes(call.dealCommitment)), tx.pure.vector("u8", bytes(call.dealNullifier)),
+            tx.pure.vector("u8", bytes(call.inputNullifier)), tx.pure.vector("u8", bytes(call.paymentCommitment)), tx.pure.vector("u8", bytes(call.changeCommitment)),
+            tx.pure.u64(call.expiryMs), tx.pure.vector("u8", bytes(call.newRoot)), tx.pure.u64(call.newIndex), tx.pure.vector("u8", bytes(call.proof)),
+        ] });
+    return tx;
+}
+export function buildWithdraw(call) {
+    validateCommon(call);
+    validateU64(call.amount, "amount", true);
+    if (!/^0x[0-9a-f]{64}$/i.test(call.recipient))
+        fail("POOL_ARGUMENT_INVALID", "recipient must be a 32-byte Sui address");
+    validate32({ root: call.root, noteNullifier: call.noteNullifier });
+    const tx = new Transaction();
+    tx.moveCall({ target: `${call.packageId}::pool::withdraw`, typeArguments: [call.coinType], arguments: [
+            tx.object(call.poolId), tx.pure.vector("u8", bytes(call.root)), tx.pure.vector("u8", bytes(call.noteNullifier)),
+            tx.pure.address(call.recipient), tx.pure.u64(call.amount), tx.pure.vector("u8", bytes(call.proof)),
+        ] });
+    return tx;
+}
+export function buildWithdrawV2(call) {
+    validateCommon(call);
+    validateU64(call.amount, "amount", true);
+    validateU64(call.newIndex, "new index", true);
+    if (!call.exactExit && call.amount !== 1000000n)
+        fail("POOL_ARGUMENT_INVALID", "standard v2 exits are 1,000,000 MIST");
+    if (!/^0x[0-9a-f]{64}$/i.test(call.recipient))
+        fail("POOL_ARGUMENT_INVALID", "recipient must be a 32-byte Sui address");
+    validate32({ root: call.root, noteNullifier: call.noteNullifier, changeCommitment: call.changeCommitment, newRoot: call.newRoot });
+    const tx = new Transaction();
+    tx.moveCall({ target: `${call.packageId}::pool_v2::withdraw`, typeArguments: [call.coinType], arguments: [
+            tx.object(call.poolId), tx.pure.vector("u8", bytes(call.root)), tx.pure.vector("u8", bytes(call.noteNullifier)),
+            tx.pure.address(call.recipient), tx.pure.u64(call.amount), tx.pure.bool(call.exactExit),
+            tx.pure.vector("u8", bytes(call.changeCommitment)), tx.pure.vector("u8", bytes(call.newRoot)),
+            tx.pure.u64(call.newIndex), tx.pure.vector("u8", bytes(call.proof)),
+        ] });
+    return tx;
+}
+export function writeClient(endpoint) { return new SuiGrpcClient({ baseUrl: endpoint, network: "testnet" }); }

package/dist/tatum.d.ts

@@ -0,0 +1,17 @@
+type BinaryMessage = {
+    toBinary(value: object): Uint8Array;
+    fromBinary(value: Uint8Array): unknown;
+};
+/** Minimal native HTTP/2 adapter because Tatum exposes gRPC, not gRPC-web. */
+export declare class TatumLedger {
+    private readonly endpoint;
+    private readonly apiKey;
+    constructor(endpoint: string, apiKey: string);
+    unary<Request extends object, Response>(method: string, requestType: BinaryMessage, responseType: BinaryMessage, message: Request): Promise<Response>;
+    stream<Request extends object, Response>(method: string, requestType: BinaryMessage, responseType: BinaryMessage, message: Request): Promise<Response[]>;
+    private call;
+    getServiceInfo(): Promise<unknown>;
+    getTransaction(digest: string): Promise<unknown>;
+    getObject(objectId: string): Promise<unknown>;
+}
+export {};

package/dist/tatum.js

@@ -0,0 +1,83 @@
+import http2 from "node:http2";
+import { GrpcTypes } from "@mysten/sui/grpc";
+import { fail, SupercutsError } from "./errors.js";
+function authority(endpoint) {
+    const url = new URL(endpoint);
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && ["127.0.0.1", "localhost", "::1"].includes(url.hostname)))
+        fail("TATUM_ENDPOINT_INVALID", "Tatum endpoint must use HTTPS except on loopback");
+    return url.origin;
+}
+function frame(bytes) {
+    const value = Buffer.from(bytes);
+    const result = Buffer.alloc(5 + value.length);
+    result.writeUInt32BE(value.length, 1);
+    value.copy(result, 5);
+    return result;
+}
+function unframe(body) {
+    const values = [];
+    let offset = 0;
+    while (offset < body.length) {
+        if (body[offset] !== 0 || offset + 5 > body.length)
+            fail("TATUM_GRPC_FRAME", "compressed or truncated gRPC response");
+        const size = body.readUInt32BE(offset + 1);
+        offset += 5;
+        if (offset + size > body.length)
+            fail("TATUM_GRPC_FRAME", "truncated gRPC response payload");
+        values.push(body.subarray(offset, offset + size));
+        offset += size;
+    }
+    return values;
+}
+/** Minimal native HTTP/2 adapter because Tatum exposes gRPC, not gRPC-web. */
+export class TatumLedger {
+    endpoint;
+    apiKey;
+    constructor(endpoint, apiKey) {
+        this.endpoint = endpoint;
+        this.apiKey = apiKey;
+        if (!apiKey || apiKey.length > 4096)
+            fail("TATUM_CONFIG_INVALID", "Tatum API key is missing or too large");
+        authority(endpoint);
+    }
+    async unary(method, requestType, responseType, message) {
+        const result = await this.call(method, frame(requestType.toBinary(message)));
+        const messages = unframe(result.body);
+        if (messages.length !== 1)
+            fail("TATUM_GRPC_FRAME", `${method} returned ${messages.length} messages`);
+        return responseType.fromBinary(messages[0]);
+    }
+    async stream(method, requestType, responseType, message) {
+        const result = await this.call(method, frame(requestType.toBinary(message)));
+        return unframe(result.body).map((value) => responseType.fromBinary(value));
+    }
+    async call(method, payload) {
+        if (!/^[A-Za-z][A-Za-z0-9]*$/.test(method))
+            fail("TATUM_METHOD_INVALID", "invalid gRPC method name");
+        const client = http2.connect(authority(this.endpoint));
+        return await new Promise((resolve, reject) => {
+            const request = client.request({ ":method": "POST", ":path": `/sui.rpc.v2.LedgerService/${method}`, "content-type": "application/grpc", te: "trailers", "x-api-key": this.apiKey });
+            const chunks = [];
+            let size = 0;
+            let status;
+            let grpcStatus;
+            let done = false;
+            const rejectOnce = (error) => { if (done)
+                return; done = true; request.close(http2.constants.NGHTTP2_CANCEL); client.close(); reject(error); };
+            request.setTimeout(20_000, () => rejectOnce(new SupercutsError("TATUM_TIMEOUT", `${method} timed out`)));
+            request.on("response", (headers) => { status = Number(headers[":status"]); if (headers["grpc-status"] !== undefined)
+                grpcStatus = String(headers["grpc-status"]); });
+            request.on("trailers", (headers) => { grpcStatus = String(headers["grpc-status"]); });
+            request.on("data", (chunk) => { size += chunk.length; if (size > 32 * 1024 * 1024)
+                return rejectOnce(new SupercutsError("TATUM_RESPONSE_TOO_LARGE", `${method} exceeded 32 MiB`)); chunks.push(chunk); });
+            request.on("error", (error) => rejectOnce(error));
+            request.on("end", () => { if (done)
+                return; done = true; client.close(); if (status !== 200 || grpcStatus !== "0")
+                return reject(new SupercutsError("TATUM_GRPC_ERROR", `${method} failed: HTTP ${status}, gRPC ${grpcStatus}`)); resolve({ body: Buffer.concat(chunks) }); });
+            request.end(payload);
+        });
+    }
+    getServiceInfo() { return this.unary("GetServiceInfo", GrpcTypes.GetServiceInfoRequest, GrpcTypes.GetServiceInfoResponse, {}); }
+    getTransaction(digest) { return this.unary("GetTransaction", GrpcTypes.GetTransactionRequest, GrpcTypes.GetTransactionResponse, { digest, readMask: { paths: ["digest", "checkpoint", "effects", "events", "balance_changes"] } }); }
+    getObject(objectId) { return this.unary("GetObject", GrpcTypes.GetObjectRequest, GrpcTypes.GetObjectResponse, { objectId, readMask: { paths: ["object_id", "content", "type"] } }); }
+}

package/dist/transcript.d.ts

@@ -0,0 +1,31 @@
+export type MessageType = "offer" | "counteroffer" | "accept" | "recovery" | "cancel";
+export interface MessageEnvelope {
+    id: string;
+    sessionId: string;
+    revision: number;
+    sequence: number;
+    parentHash: string | null;
+    author: string;
+    type: MessageType;
+    expiresAt: number;
+    ciphertext: string;
+    ciphertextHash: string;
+    signature: string;
+}
+export interface TranscriptConstraints {
+    sessionId?: string;
+    participants?: ReadonlySet<string>;
+    now?: number;
+    allowExpired?: boolean;
+}
+export type SignatureVerifier = (author: string, bytes: Uint8Array, signature: string) => Promise<boolean>;
+export type CiphertextLoader = (blobId: string) => Promise<string>;
+export declare function canonicalEnvelope(envelope: Omit<MessageEnvelope, "signature">): Uint8Array;
+export declare function sha256(value: string | Uint8Array): string;
+export declare function validateTranscript(messages: MessageEnvelope[], verify: SignatureVerifier, constraints?: number | TranscriptConstraints): Promise<string>;
+export declare function hydrateTranscript(manifest: Array<Omit<MessageEnvelope, "ciphertext"> & {
+    blobId: string;
+}>, load: CiphertextLoader, verify: SignatureVerifier, constraints?: number | TranscriptConstraints): Promise<{
+    messages: MessageEnvelope[];
+    root: string;
+}>;

package/dist/transcript.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { fail } from "./errors.js";
+export function canonicalEnvelope(envelope) {
+    return Buffer.from(JSON.stringify({
+        id: envelope.id, sessionId: envelope.sessionId, revision: envelope.revision, sequence: envelope.sequence,
+        parentHash: envelope.parentHash, author: envelope.author, type: envelope.type, expiresAt: envelope.expiresAt,
+        ciphertextHash: envelope.ciphertextHash,
+    }));
+}
+export function sha256(value) { return createHash("sha256").update(value).digest("hex"); }
+export async function validateTranscript(messages, verify, constraints = {}) {
+    if (!messages.length)
+        fail("TRANSCRIPT_EMPTY", "a settlement transcript cannot be empty");
+    const options = typeof constraints === "number" ? { now: constraints } : constraints;
+    const now = options.now ?? Date.now();
+    const sessionId = options.sessionId ?? messages[0].sessionId;
+    let previous = null;
+    const seen = new Set();
+    let revision = 0;
+    for (let position = 0; position < messages.length; position++) {
+        const message = messages[position];
+        if (!message.id || message.id.length > 256 || !message.sessionId || message.sessionId.length > 256 || !message.author || message.author.length > 256 || !Number.isSafeInteger(message.sequence) || !Number.isSafeInteger(message.expiresAt) || message.ciphertext.length > 2_000_000)
+            fail("TRANSCRIPT_MESSAGE_INVALID", "transcript message fields are invalid or too large");
+        if (!["offer", "counteroffer", "accept", "recovery", "cancel"].includes(message.type))
+            fail("TRANSCRIPT_MESSAGE_INVALID", "transcript message type is invalid");
+        if (message.sequence !== position || seen.has(message.id))
+            fail("TRANSCRIPT_ORDER_INVALID", "transcript has a gap, duplicate, or replay");
+        if (message.sessionId !== sessionId)
+            fail("TRANSCRIPT_SESSION_MISMATCH", "message belongs to another session");
+        if (options.participants && !options.participants.has(message.author))
+            fail("TRANSCRIPT_PEER_MISMATCH", "message author is not a session participant");
+        if (!Number.isSafeInteger(message.revision) || message.revision < 1 || message.revision < revision || message.revision > revision + 1)
+            fail("TRANSCRIPT_REVISION_INVALID", "message revision is not monotonic");
+        if (message.parentHash !== previous)
+            fail("TRANSCRIPT_FORK", "transcript parent hash does not match its predecessor");
+        if (!options.allowExpired && message.expiresAt < now && message.type !== "cancel")
+            fail("OFFER_EXPIRED", "transcript contains an expired message");
+        const ciphertext = Buffer.from(message.ciphertext, "base64");
+        if (ciphertext.toString("base64") !== message.ciphertext || sha256(ciphertext) !== message.ciphertextHash)
+            fail("CIPHERTEXT_TAMPERED", "ciphertext encoding or hash does not match");
+        if (!(await verify(message.author, canonicalEnvelope(message), message.signature)))
+            fail("MESSAGE_SIGNATURE_INVALID", "message signature is invalid");
+        previous = sha256(Buffer.concat([canonicalEnvelope(message), Buffer.from(message.signature)]));
+        revision = message.revision;
+        seen.add(message.id);
+    }
+    return previous;
+}
+export async function hydrateTranscript(manifest, load, verify, constraints = {}) {
+    const messages = await Promise.all(manifest.map(async ({ blobId, ...message }) => ({ ...message, ciphertext: await load(blobId) })));
+    return { messages, root: await validateTranscript(messages, verify, constraints) };
+}

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

@@ -0,0 +1,34 @@
+import type { RoleStore } from "./store.js";
+import { type WithdrawV2Call } from "./sui.js";
+export interface V2RelayerPin {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    relayerAddress: string;
+    writeGrpcEndpoint: string;
+    tatumGrpcEndpoint: string;
+}
+export interface V2ExitRequest extends Omit<WithdrawV2Call, "packageId" | "poolId" | "coinType"> {
+    operationId: string;
+}
+/** Runs in a separate, funded relayer home. It never receives a note opening. */
+export declare class V2ExitRelayer {
+    private readonly store;
+    private readonly pin;
+    private readonly client;
+    private readonly signer;
+    private readonly tatum;
+    constructor(store: RoleStore, pin: V2RelayerPin);
+    doctor(): Promise<{
+        relayer: string;
+        gasBalanceMist: string;
+        funded: true;
+    }>;
+    submit(request: V2ExitRequest): Promise<{
+        digest: string;
+        checkpoint: string;
+        relayer: string;
+        resumed: boolean;
+        tatumVerified: true;
+    }>;
+}

package/dist/v2-exit-relayer.js

@@ -0,0 +1,102 @@
+import { createHash } from "node:crypto";
+import { decodeSuiPrivateKey } from "@mysten/sui/cryptography";
+import { Ed25519Keypair } from "@mysten/sui/keypairs/ed25519";
+import { fail } from "./errors.js";
+import { assertSuiFinality, assertTatumFinality } from "./finality.js";
+import { buildWithdrawV2, writeClient } from "./sui.js";
+import { TatumLedger } from "./tatum.js";
+/** Runs in a separate, funded relayer home. It never receives a note opening. */
+export class V2ExitRelayer {
+    store;
+    pin;
+    client;
+    signer;
+    tatum;
+    constructor(store, pin) {
+        this.store = store;
+        this.pin = pin;
+        const encoded = store.getSecret("live:relayer-sui-private-key")?.toString() ?? fail("RELAYER_CREDENTIAL_MISSING", "separate relayer signer is missing");
+        const decoded = decodeSuiPrivateKey(encoded);
+        if (decoded.scheme !== "ED25519")
+            fail("SIGNER_UNSUPPORTED", "relayer signer must use ED25519");
+        this.signer = Ed25519Keypair.fromSecretKey(decoded.secretKey);
+        if (this.signer.toSuiAddress().toLowerCase() !== pin.relayerAddress.toLowerCase())
+            fail("RELAYER_SIGNER_MISMATCH", "relayer signer differs from the pinned funded address");
+        this.client = writeClient(pin.writeGrpcEndpoint);
+        const tatumKey = store.getSecret("live:tatum-api-key")?.toString() ?? fail("RELAYER_CREDENTIAL_MISSING", "relayer Tatum read credential is missing");
+        this.tatum = new TatumLedger(pin.tatumGrpcEndpoint, tatumKey);
+        store.db.exec(`CREATE TABLE IF NOT EXISTS v2_relay_journal (
+      operation_id TEXT PRIMARY KEY, request_hash TEXT NOT NULL, note_nullifier TEXT NOT NULL UNIQUE,
+      transaction_bytes BLOB NOT NULL, signature TEXT NOT NULL, digest TEXT NOT NULL UNIQUE,
+      status TEXT NOT NULL, updated_at INTEGER NOT NULL
+    )`);
+    }
+    async doctor() {
+        const { balance } = await this.client.getBalance({ owner: this.signer.toSuiAddress(), coinType: "0x2::sui::SUI" });
+        const available = BigInt(balance.balance);
+        if (available < 10000000n)
+            fail("RELAYER_GAS_INSUFFICIENT", "separate Testnet relayer needs at least 10,000,000 MIST for the live exit gate");
+        return { relayer: this.signer.toSuiAddress(), gasBalanceMist: available.toString(), funded: true };
+    }
+    async submit(request) {
+        if (!request.operationId || request.operationId.length > 256)
+            fail("RELAY_REQUEST_INVALID", "operation ID is invalid");
+        if ([request.root, request.noteNullifier, request.changeCommitment, request.newRoot].some((value) => value.length !== 32) ||
+            !/^0x[0-9a-f]{64}$/i.test(request.recipient) || request.amount <= 0n || request.amount >= 1n << 64n ||
+            (!request.exactExit && request.amount !== 1000000n) || request.newIndex <= 0n ||
+            !request.proof.length || request.proof.length > 128 * 1024)
+            fail("RELAY_REQUEST_INVALID", "v2 exit fields are malformed or outside protocol bounds");
+        const normalized = {
+            operationId: request.operationId, root: Buffer.from(request.root).toString("hex"),
+            noteNullifier: Buffer.from(request.noteNullifier).toString("hex"), recipient: request.recipient.toLowerCase(),
+            amount: request.amount.toString(), exactExit: request.exactExit,
+            changeCommitment: Buffer.from(request.changeCommitment).toString("hex"),
+            newRoot: Buffer.from(request.newRoot).toString("hex"), newIndex: request.newIndex.toString(),
+            proofHash: createHash("sha256").update(request.proof).digest("hex"),
+        };
+        const requestHash = createHash("sha256").update(JSON.stringify(normalized)).digest("hex");
+        const existing = this.store.db.prepare("SELECT request_hash,transaction_bytes,signature,digest FROM v2_relay_journal WHERE operation_id=?").get(request.operationId);
+        if (existing && existing.request_hash !== requestHash)
+            fail("OPERATION_ID_CONFLICT", "relayer operation ID identifies another proof or payout");
+        let signed;
+        if (existing)
+            signed = { transaction: existing.transaction_bytes, signature: existing.signature, digest: existing.digest };
+        else {
+            await this.doctor();
+            const tx = buildWithdrawV2({ ...request, packageId: this.pin.packageId, poolId: this.pin.poolId, coinType: this.pin.coinType });
+            tx.setSender(this.signer.toSuiAddress());
+            const simulation = await this.client.simulateTransaction({ transaction: tx, include: { effects: true } });
+            if (!(simulation.Transaction ?? simulation.FailedTransaction)?.status.success)
+                fail("RELAY_SIMULATION_FAILED", "v2 withdrawal proof or current root was rejected");
+            const transaction = await tx.build({ client: this.client });
+            const digest = await tx.getDigest({ client: this.client });
+            const signature = (await this.signer.signTransaction(transaction)).signature;
+            try {
+                this.store.db.prepare("INSERT INTO v2_relay_journal(operation_id,request_hash,note_nullifier,transaction_bytes,signature,digest,status,updated_at) VALUES(?,?,?,?,?,?,'signed',?)")
+                    .run(request.operationId, requestHash, normalized.noteNullifier, Buffer.from(transaction), signature, digest, Date.now());
+            }
+            catch (error) {
+                fail("RELAY_REPLAY", "nullifier or operation has already been submitted through this relayer", error);
+            }
+            signed = { transaction, signature, digest };
+        }
+        try {
+            await this.client.executeTransaction({ transaction: signed.transaction, signatures: [signed.signature], include: { effects: true } });
+        }
+        catch {
+            // An ambiguous broadcast is resolved by the digest. The exact signed
+            // bytes remain journaled, so a retry cannot change the payout.
+        }
+        let finalized;
+        try {
+            finalized = await this.client.waitForTransaction({ digest: signed.digest, timeout: 60_000, include: { effects: true } });
+        }
+        catch (error) {
+            return fail("RELAY_BROADCAST_UNRESOLVED", "relayer transaction outcome is unresolved; retry the same operation ID", error);
+        }
+        const checkpoint = assertSuiFinality(finalized, signed.digest);
+        assertTatumFinality(await this.tatum.getTransaction(signed.digest), signed.digest, checkpoint);
+        this.store.db.prepare("UPDATE v2_relay_journal SET status='finalized',updated_at=? WHERE operation_id=?").run(Date.now(), request.operationId);
+        return { digest: signed.digest, checkpoint, relayer: this.signer.toSuiAddress(), resumed: Boolean(existing), tatumVerified: true };
+    }
+}

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[]>;
+}