@supercuts-walrus/backend 0.0.0-stage → 0.1.1

package/dist/store.js

@@ -0,0 +1,193 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { fail } from "./errors.js";
+const statuses = new Set(["draft", "reserved", "proof_persisted", "broadcast", "finalized", "confirmed", "delivered", "unresolved"]);
+function encrypt(key, value, aad) {
+    const nonce = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, nonce);
+    cipher.setAAD(Buffer.from(aad));
+    return { nonce, value: Buffer.concat([cipher.update(value), cipher.final()]), tag: cipher.getAuthTag() };
+}
+function decrypt(key, encrypted, aad) {
+    try {
+        const cipher = createDecipheriv("aes-256-gcm", key, encrypted.nonce);
+        cipher.setAAD(Buffer.from(aad));
+        cipher.setAuthTag(encrypted.tag);
+        return Buffer.concat([cipher.update(encrypted.value), cipher.final()]);
+    }
+    catch (error) {
+        return fail("STATE_DECRYPT_FAILED", `could not decrypt ${aad}`, error);
+    }
+}
+export class RoleStore {
+    db;
+    #key;
+    constructor(path, key) {
+        if (key.length !== 32)
+            fail("STATE_KEY_INVALID", "role-store key must contain exactly 32 bytes");
+        this.#key = Buffer.from(key);
+        const directory = dirname(path);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        if ((statSync(directory).mode & 0o077) !== 0)
+            fail("STATE_DIRECTORY_PERMISSIONS", `${directory} must not be group/world accessible`);
+        if (existsSync(path) && (statSync(path).mode & 0o077) !== 0)
+            fail("STATE_PERMISSIONS", `${path} must not be group/world accessible`);
+        this.db = new DatabaseSync(path);
+        // SQLite may create the main database before its first transaction. Ensure
+        // the database and any persistent WAL sidecars cannot expose encrypted
+        // ciphertext or public operation metadata to another local account.
+        for (const candidate of [path, `${path}-wal`, `${path}-shm`]) {
+            if (existsSync(candidate))
+                chmodSync(candidate, 0o600);
+        }
+        this.db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS secrets (name TEXT PRIMARY KEY, nonce BLOB NOT NULL, tag BLOB NOT NULL, value BLOB NOT NULL);
+      CREATE TABLE IF NOT EXISTS operations (id TEXT PRIMARY KEY, status TEXT NOT NULL, payload_hash TEXT NOT NULL, tx_digest TEXT, updated_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS reservations (note_commitment TEXT PRIMARY KEY, operation_id TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS replay_ledger (scope TEXT NOT NULL, value TEXT NOT NULL, result TEXT, PRIMARY KEY(scope, value));
+      CREATE TABLE IF NOT EXISTS checkpoints (stream TEXT PRIMARY KEY, checkpoint TEXT NOT NULL, cursor BLOB, root TEXT NOT NULL, leaf_index TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS messages (id TEXT PRIMARY KEY, session_id TEXT NOT NULL, sequence INTEGER NOT NULL, ciphertext_hash TEXT NOT NULL, blob_id TEXT, UNIQUE(session_id, sequence));
+      CREATE TABLE IF NOT EXISTS deliveries (request_id TEXT PRIMARY KEY, payment_key TEXT NOT NULL, response BLOB NOT NULL, finalized INTEGER NOT NULL);
+      CREATE UNIQUE INDEX IF NOT EXISTS deliveries_payment_key ON deliveries(payment_key);
+      CREATE TABLE IF NOT EXISTS x402_challenges (request_id TEXT PRIMARY KEY, nonce TEXT NOT NULL, requirements_hash TEXT NOT NULL, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS delivery_jobs (request_id TEXT PRIMARY KEY, status TEXT NOT NULL, lease_until INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS notes (commitment TEXT PRIMARY KEY, operation_id TEXT, role TEXT NOT NULL, leaf_index TEXT, nullifier TEXT, spent INTEGER NOT NULL DEFAULT 0);
+      CREATE TABLE IF NOT EXISTS memory_jobs (operation_id TEXT PRIMARY KEY, kind TEXT NOT NULL, fact_hash TEXT NOT NULL, blob_id TEXT, status TEXT NOT NULL, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS memory_authority (blob_id TEXT PRIMARY KEY, fact_hash TEXT NOT NULL, provenance TEXT NOT NULL, evidence_hash TEXT, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS memory_inventory (blob_id TEXT PRIMARY KEY, memory_id TEXT NOT NULL, namespace TEXT NOT NULL, status TEXT NOT NULL, expires_at TEXT, deleted INTEGER NOT NULL DEFAULT 0, updated_at TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS memory_inventory_cursor (namespace TEXT PRIMARY KEY, cursor TEXT, updated_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS deal_operations (operation_id TEXT PRIMARY KEY, deal_id TEXT NOT NULL UNIQUE, input_hash TEXT NOT NULL, state TEXT NOT NULL, rail TEXT, plan_hash TEXT, payment_operation_id TEXT NOT NULL UNIQUE, created_at INTEGER NOT NULL, updated_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS deal_steps (operation_id TEXT NOT NULL, step TEXT NOT NULL, input_hash TEXT NOT NULL, state TEXT NOT NULL, result_hash TEXT, updated_at INTEGER NOT NULL, PRIMARY KEY(operation_id,step), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS deal_blobs (operation_id TEXT NOT NULL, kind TEXT NOT NULL, ciphertext_hash TEXT NOT NULL, blob_id TEXT, status TEXT NOT NULL, PRIMARY KEY(operation_id,kind), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS deal_memory_outbox (operation_id TEXT NOT NULL, event_kind TEXT NOT NULL, payload_hash TEXT NOT NULL, blob_id TEXT, status TEXT NOT NULL, updated_at INTEGER NOT NULL, PRIMARY KEY(operation_id,event_kind), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS deal_timings (operation_id TEXT NOT NULL, stage TEXT NOT NULL, duration_ms INTEGER NOT NULL, PRIMARY KEY(operation_id,stage), FOREIGN KEY(operation_id) REFERENCES deal_operations(operation_id));
+      CREATE TABLE IF NOT EXISTS settlement_plans (plan_hash TEXT PRIMARY KEY, operation_id TEXT NOT NULL UNIQUE, plan_json TEXT NOT NULL, status TEXT NOT NULL, expires_at INTEGER NOT NULL, consumed_at INTEGER, created_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS settlement_execution_bindings (operation_id TEXT PRIMARY KEY, plan_hash TEXT NOT NULL UNIQUE, binding_hash TEXT NOT NULL, binding_json TEXT NOT NULL, created_at INTEGER NOT NULL, FOREIGN KEY(plan_hash) REFERENCES settlement_plans(plan_hash));
+      CREATE TABLE IF NOT EXISTS settlement_agreement_bindings (session_id TEXT PRIMARY KEY, plan_hash TEXT NOT NULL UNIQUE, binding_hash TEXT NOT NULL, created_at INTEGER NOT NULL, FOREIGN KEY(plan_hash) REFERENCES settlement_plans(plan_hash));
+      CREATE TABLE IF NOT EXISTS settlement_decision_traces (plan_hash TEXT PRIMARY KEY, mandate_hash TEXT NOT NULL, manifest_hash TEXT NOT NULL, risk_level TEXT NOT NULL, reason_codes TEXT NOT NULL, citations TEXT NOT NULL, created_at INTEGER NOT NULL, FOREIGN KEY(plan_hash) REFERENCES settlement_plans(plan_hash));
+    `);
+        const memoryColumns = this.db.prepare("PRAGMA table_info(memory_jobs)").all();
+        if (!memoryColumns.some((column) => column.name === "fact_hash"))
+            this.db.exec("ALTER TABLE memory_jobs ADD COLUMN fact_hash TEXT");
+        if (!memoryColumns.some((column) => column.name === "claimed_at"))
+            this.db.exec("ALTER TABLE memory_jobs ADD COLUMN claimed_at INTEGER");
+        for (const candidate of [path, `${path}-wal`, `${path}-shm`])
+            if (existsSync(candidate))
+                chmodSync(candidate, 0o600);
+    }
+    close() { this.db.close(); }
+    putSecret(name, value) {
+        const encrypted = encrypt(this.#key, Buffer.from(value), `secret:${name}`);
+        this.db.prepare("INSERT OR REPLACE INTO secrets(name, nonce, tag, value) VALUES (?, ?, ?, ?)")
+            .run(name, encrypted.nonce, encrypted.tag, encrypted.value);
+    }
+    putSecretOnce(name, value) {
+        const existing = this.getSecret(name);
+        if (existing) {
+            if (!existing.equals(Buffer.from(value)))
+                fail("SECRET_ID_CONFLICT", `secret ${name} already contains different bytes`);
+            return;
+        }
+        this.putSecret(name, value);
+    }
+    getSecret(name) {
+        const row = this.db.prepare("SELECT nonce, tag, value FROM secrets WHERE name = ?").get(name);
+        return row ? decrypt(this.#key, row, `secret:${name}`) : undefined;
+    }
+    beginOperation(id, payloadHash) {
+        const existing = this.getOperation(id);
+        if (existing) {
+            if (existing.payloadHash !== payloadHash)
+                fail("OPERATION_ID_CONFLICT", `operation ${id} already has a different payload`);
+            return;
+        }
+        this.db.prepare("INSERT INTO operations(id, status, payload_hash, updated_at) VALUES (?, 'draft', ?, ?)").run(id, payloadHash, Date.now());
+    }
+    getOperation(id) {
+        const row = this.db.prepare("SELECT id, status, payload_hash, tx_digest, updated_at FROM operations WHERE id = ?").get(id);
+        return row ? { id: row.id, status: row.status, payloadHash: row.payload_hash, ...(row.tx_digest ? { txDigest: row.tx_digest } : {}), updatedAt: row.updated_at } : undefined;
+    }
+    transitionOperation(id, next, txDigest) {
+        if (!statuses.has(next))
+            fail("OPERATION_STATUS_INVALID", `unknown operation status ${next}`);
+        const row = this.db.prepare("SELECT status, tx_digest FROM operations WHERE id = ?").get(id);
+        const current = row?.status ?? fail("OPERATION_NOT_FOUND", `operation ${id} does not exist`);
+        if (row?.tx_digest && txDigest && row.tx_digest !== txDigest)
+            fail("OPERATION_DIGEST_CONFLICT", "operation cannot transition with a different transaction digest");
+        if (current === next)
+            return;
+        const allowed = {
+            draft: ["reserved", "unresolved"], reserved: ["proof_persisted", "unresolved"],
+            proof_persisted: ["broadcast", "unresolved"], broadcast: ["finalized", "unresolved"],
+            finalized: ["confirmed", "unresolved"], confirmed: ["delivered", "unresolved"], delivered: [],
+            unresolved: ["broadcast", "finalized", "confirmed"],
+        };
+        if (!allowed[current].includes(next))
+            fail("OPERATION_TRANSITION_INVALID", `${current} cannot transition to ${next}`);
+        this.db.prepare("UPDATE operations SET status = ?, tx_digest = COALESCE(?, tx_digest), updated_at = ? WHERE id = ?")
+            .run(next, txDigest ?? null, Date.now(), id);
+    }
+    reserveNote(noteCommitment, operationId) {
+        this.db.exec("BEGIN IMMEDIATE");
+        try {
+            const existing = this.db.prepare("SELECT operation_id FROM reservations WHERE note_commitment = ?").get(noteCommitment);
+            if (existing && existing.operation_id !== operationId)
+                fail("NOTE_RESERVED", "note is already reserved by another operation");
+            this.db.prepare("INSERT OR IGNORE INTO reservations(note_commitment, operation_id, created_at) VALUES (?, ?, ?)").run(noteCommitment, operationId, Date.now());
+            if (this.getOperation(operationId)?.status === "draft")
+                this.transitionOperation(operationId, "reserved");
+            this.db.exec("COMMIT");
+        }
+        catch (error) {
+            this.db.exec("ROLLBACK");
+            throw error;
+        }
+    }
+    claimOnce(scope, value, result) {
+        const info = this.db.prepare("INSERT OR IGNORE INTO replay_ledger(scope, value, result) VALUES (?, ?, ?)").run(scope, value, result ?? null);
+        return info.changes === 1;
+    }
+    prepareMessage(message) {
+        const existing = this.getMessage(message.id);
+        if (existing) {
+            if (existing.sessionId !== message.sessionId || existing.sequence !== message.sequence || existing.ciphertextHash !== message.ciphertextHash) {
+                fail("MESSAGE_ID_CONFLICT", `message ${message.id} already identifies different ciphertext`);
+            }
+            return;
+        }
+        try {
+            this.db.prepare("INSERT INTO messages(id, session_id, sequence, ciphertext_hash, blob_id) VALUES (?, ?, ?, ?, NULL)")
+                .run(message.id, message.sessionId, message.sequence, message.ciphertextHash);
+        }
+        catch (error) {
+            fail("MESSAGE_SEQUENCE_CONFLICT", "session sequence is already occupied", error);
+        }
+    }
+    attachMessageBlob(id, ciphertextHash, blobId) {
+        const row = this.getMessage(id) ?? fail("MESSAGE_NOT_FOUND", `message ${id} was not prepared`);
+        if (row.ciphertextHash !== ciphertextHash)
+            fail("CIPHERTEXT_TAMPERED", "uploaded ciphertext differs from the durable message");
+        if (row.blobId && row.blobId !== blobId)
+            fail("MESSAGE_BLOB_CONFLICT", "message already resolved to another blob");
+        this.db.prepare("UPDATE messages SET blob_id = ? WHERE id = ?").run(blobId, id);
+    }
+    getMessage(id) {
+        const row = this.db.prepare("SELECT id, session_id, sequence, ciphertext_hash, blob_id FROM messages WHERE id = ?").get(id);
+        return row ? { id: row.id, sessionId: row.session_id, sequence: row.sequence, ciphertextHash: row.ciphertext_hash, ...(row.blob_id ? { blobId: row.blob_id } : {}) } : undefined;
+    }
+    putNote(commitment, role, operationId, leafIndex, nullifier) {
+        const existing = this.db.prepare("SELECT operation_id, role, leaf_index, nullifier FROM notes WHERE commitment = ?").get(commitment);
+        const values = { operationId: operationId ?? null, role, leafIndex: leafIndex?.toString() ?? null, nullifier: nullifier ?? null };
+        if (existing && (existing.operation_id !== values.operationId || existing.role !== role || (existing.leaf_index && values.leafIndex && existing.leaf_index !== values.leafIndex) || (existing.nullifier && values.nullifier && existing.nullifier !== values.nullifier)))
+            fail("NOTE_ID_CONFLICT", "note commitment is already associated with different recovery data");
+        this.db.prepare("INSERT INTO notes(commitment, operation_id, role, leaf_index, nullifier, spent) VALUES (?, ?, ?, ?, ?, 0) ON CONFLICT(commitment) DO UPDATE SET leaf_index=COALESCE(notes.leaf_index, excluded.leaf_index), nullifier=COALESCE(notes.nullifier, excluded.nullifier)")
+            .run(commitment, values.operationId, role, values.leafIndex, values.nullifier);
+    }
+    markNoteSpent(nullifier) { this.db.prepare("UPDATE notes SET spent = 1 WHERE nullifier = ?").run(nullifier); }
+    hasUnspentNote(commitment) {
+        return Boolean(this.db.prepare("SELECT 1 AS found FROM notes WHERE commitment = ? AND spent = 0").get(commitment));
+    }
+}

package/dist/sui.d.ts

@@ -0,0 +1,49 @@
+import { SuiGrpcClient } from "@mysten/sui/grpc";
+import { Transaction } from "@mysten/sui/transactions";
+export interface TransferCall {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    poolModule?: "pool" | "pool_v2";
+    expiryMs: bigint;
+    newIndex: bigint;
+    dealCommitment: Uint8Array;
+    dealNullifier: Uint8Array;
+    inputNullifier: Uint8Array;
+    paymentCommitment: Uint8Array;
+    changeCommitment: Uint8Array;
+    newRoot: Uint8Array;
+    proof: Uint8Array;
+}
+export interface DepositCall {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    poolModule?: "pool" | "pool_v2";
+    amount: bigint;
+    newIndex: bigint;
+    noteCommitment: Uint8Array;
+    newRoot: Uint8Array;
+    proof: Uint8Array;
+}
+export interface WithdrawCall {
+    packageId: string;
+    poolId: string;
+    coinType: string;
+    amount: bigint;
+    recipient: string;
+    root: Uint8Array;
+    noteNullifier: Uint8Array;
+    proof: Uint8Array;
+}
+export interface WithdrawV2Call extends WithdrawCall {
+    exactExit: boolean;
+    changeCommitment: Uint8Array;
+    newRoot: Uint8Array;
+    newIndex: bigint;
+}
+export declare function buildDeposit(call: DepositCall): Transaction;
+export declare function buildPrivateTransfer(call: TransferCall): Transaction;
+export declare function buildWithdraw(call: WithdrawCall): Transaction;
+export declare function buildWithdrawV2(call: WithdrawV2Call): Transaction;
+export declare function writeClient(endpoint: string): SuiGrpcClient;

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