cascrow-signer 0.1.0

package/dist/actions.js

@@ -0,0 +1,319 @@
+/**
+ * One function per escrow action. Each one: unlock the key, read what it needs
+ * from the CHAIN, build the calldata itself from the pinned ABI, run the checks
+ * (checks.ts), then — inside the journal lock — reserve, sign, send to the
+ * pinned public RPC, and finally report the hash to cascrow, best effort.
+ *
+ * `fund` needs cascrow: the payee's acceptance signature and the frozen terms
+ * come from `prepare?action=fund`. `submitClaim` needs it too, for one fact only:
+ * that the proof hash is a submission cascrow SEALED for the milestone (a claim
+ * naming anything else has no verdict — post-review G2). Every other action is
+ * built from the escrow ID and the chain alone; `prepare` is fetched only as a
+ * cross-check, and an UNREACHABLE cascrow never stops a payer from objecting,
+ * releasing or refunding (design Rev. 10, "Nach der Finanzierung ohne Server").
+ * A cascrow that ANSWERS with a refusal (a 4xx with its code) is surfaced as that
+ * refusal, never read as "down" (post-review G1/H2).
+ */
+import fs from "node:fs";
+import { getAddress, keccak256, parseEther, sha256, toUtf8Bytes } from "ethers";
+import { SignerError, refuse } from "./errors.js";
+import { PER_ESCROW_ACTIONS, encodeCall } from "./calldata.js";
+import { BOOK_BOUND_ACTIONS, checkEscrowAction, checkFund, checkMatchesLocal, checkPreparedEnvelope, checkWithdraw, fundTermsFrom } from "./checks.js";
+import { fundedByMeLastDay, latestBlock, readCredit, readEscrow, sendSigned, settleUnknown } from "./chain.js";
+import { withLock } from "./journal.js";
+import { loadPolicy, savePolicy } from "./policy.js";
+import { Book } from "./book.js";
+import { RemoteError } from "./remote.js";
+import { verifyEndpoint } from "./network.js";
+import { manifestHash, contentHashFor } from "./generated/v3-proof-manifest.js";
+function chainCtx(ctx) {
+    return { rpc: ctx.rpc, net: ctx.net };
+}
+async function report(ctx, milestoneId, txHash, notes) {
+    if (!milestoneId || !ctx.remote.configured) {
+        notes.push("sent, not reported to cascrow (no milestone or no API key) — cascrow's indexer reads it from the chain anyway");
+        return false;
+    }
+    try {
+        await ctx.remote.reportTx(milestoneId, txHash);
+        return true;
+    }
+    catch {
+        notes.push("sent, not reported to cascrow — its indexer reads the chain within minutes; do NOT send again");
+        return false;
+    }
+}
+export async function fund(ctx, input) {
+    if (!input.milestoneId)
+        refuse("INPUT", "milestoneId is required");
+    const maxAmountWei = input.maxAmountXrp ? parseEther(input.maxAmountXrp) : null;
+    const key = await ctx.unlock();
+    const me = key.address;
+    let policy = loadPolicy(ctx.home, key.macKey, me);
+    const book = new Book(ctx.home, key.macKey);
+    const notes = [];
+    let raw;
+    try {
+        raw = await ctx.remote.prepare({ milestoneId: input.milestoneId, action: "fund" });
+    }
+    catch (e) {
+        if (isPrepareRefusal(e)) {
+            const detail = refusalDetail(e.body);
+            throw new SignerError(e.code ?? "PREPARE_REFUSED", `cascrow refused to prepare fund: ${typeof e.body.error === "string" && e.body.error ? e.body.error : `HTTP ${e.status}`}${detail ? ` — ${detail}` : ""}. Nothing was signed`);
+        }
+        refuse("PREPARE_UNAVAILABLE", `funding needs the payee's acceptance from cascrow, and prepare failed: ${e instanceof Error ? e.message : "error"}`);
+    }
+    const p = checkPreparedEnvelope(raw, "fund", ctx.net, me);
+    const terms = fundTermsFrom(p);
+    // First contact with a payee: only a person at a terminal adds it to the book.
+    if (!policy.payees.includes(terms.t.payee.toLowerCase()) && ctx.io.isTTY && ctx.io.confirm) {
+        const ok = await ctx.io.confirm(`Payee ${terms.t.payee} is not in your counterparty book. Add it (raises the limit to your per-escrow limit)?`);
+        if (ok) {
+            policy = { ...policy, payees: [...policy.payees, terms.t.payee.toLowerCase()].sort() };
+            savePolicy(ctx.home, key.macKey, policy, ctx.io);
+        }
+    }
+    const c = chainCtx(ctx);
+    return withLock(ctx.home, async () => {
+        await verifyEndpoint(ctx.rpc, ctx.net);
+        const head = await latestBlock(c);
+        const journalPresent = ctx.journal.exists();
+        const fromJournal = ctx.journal.daySum(head.timestamp);
+        let fromChain;
+        try {
+            fromChain = await fundedByMeLastDay(c, me, head);
+        }
+        catch (e) {
+            if (!journalPresent) {
+                refuse("JOURNAL_UNREADABLE", "the spending journal is missing and the chain's Funded events could not be read to rebuild today's total — funding is refused rather than guessing the daily limit");
+            }
+            notes.push(`could not cross-check today's total against the chain (${e instanceof Error ? e.message : "error"}); used the local journal`);
+            fromChain = new Map();
+        }
+        let day = fromJournal.sumWei;
+        for (const [id, amt] of fromChain)
+            if (!fromJournal.escrowIds.has(id))
+                day += amt;
+        if (!journalPresent)
+            notes.push("the spending journal was missing; today's total was rebuilt from Funded events on chain");
+        try {
+            await settleUnknown(c, me, ctx.journal);
+        }
+        catch {
+            /* unknown outcomes keep counting — the safe direction */
+        }
+        const slot = await readEscrow(c, p.escrowId);
+        const { payeeKnown } = checkFund({ prepared: p, terms, me, pinned: ctx.net, policy, daySumWei: day, chainNowSec: head.timestamp, slotStatus: slot.status, maxAmountWei });
+        if (!payeeKnown)
+            notes.push("payee not in your counterparty book — the lower limit for unknown payees applied");
+        if (!journalPresent)
+            ctx.journal.create(true);
+        const rid = ctx.journal.reserve("fund", p.escrowId, terms.t.amount, head.timestamp);
+        book.add({ escrowId: p.escrowId, role: "payer", milestoneId: input.milestoneId, payer: me, payee: terms.t.payee, amountWei: terms.t.amount.toString(), chainId: ctx.net.chainId, contract: ctx.net.address, at: head.timestamp });
+        const data = encodeCall("fund", p.call.args);
+        const sent = await sendSigned(c, key, ctx.journal, rid, { to: ctx.net.address, data, value: terms.t.amount });
+        if (sent.note)
+            notes.push(sent.note);
+        const reported = await report(ctx, input.milestoneId, sent.txHash, notes);
+        return {
+            action: "fund",
+            escrowId: p.escrowId,
+            txHash: sent.txHash,
+            sent: sent.sent,
+            reported,
+            from: me,
+            amountWei: terms.t.amount.toString(),
+            payee: terms.t.payee,
+            notes,
+        };
+    });
+}
+/**
+ * The manifest hash of evidence the payee holds locally, computed HERE with the
+ * one manifest encoding. A submission is what ONE evidence-door request sealed —
+ * today one file, one text or one GitHub item — so the hash of several items only
+ * matches a submission that sealed exactly those items. It is never trusted on
+ * its own: `submitClaim` sends it only after cascrow's prepare confirms it is a
+ * sealed submission of the milestone (post-review G2).
+ */
+export function localProofHash(milestoneId, ev) {
+    const items = [];
+    for (const f of ev.files ?? [])
+        items.push({ kind: "file", sha256: sha256(fs.readFileSync(f)) });
+    for (const t of ev.texts ?? [])
+        items.push({ kind: "text", text: t });
+    for (const g of ev.github ?? [])
+        items.push({ kind: "github", commitSha: g.commitSha, diffSha256: g.diffSha256 });
+    if (!items.length)
+        refuse("INPUT", "submitClaim needs proofHash (the manifestHash the evidence door returned) or the evidence file(s) to hash locally");
+    return manifestHash(milestoneId, items.map(contentHashFor));
+}
+const hasEvidence = (ev) => !!ev && ((ev.files?.length ?? 0) + (ev.texts?.length ?? 0) + (ev.github?.length ?? 0)) > 0;
+/**
+ * The fields of a refusal body a recipient can act on, as one line. The same
+ * fields every cascrow client appends (post-review G5).
+ */
+export function refusalDetail(body) {
+    const out = [];
+    if (typeof body.remedy === "string" && body.remedy)
+        out.push(body.remedy);
+    if (Array.isArray(body.allowed))
+        out.push(`allowed now: ${body.allowed.length ? body.allowed.map(String).join(", ") : "nothing"}`);
+    if (typeof body.objectionDeadline === "string")
+        out.push(`objection deadline: ${body.objectionDeadline}`);
+    if (typeof body.offerExpiresAt === "string")
+        out.push(`offer expires: ${body.offerExpiresAt}`);
+    return out.join(" — ");
+}
+/**
+ * Status codes that are an answer about cascrow's REACHABILITY for this caller,
+ * not about the transaction: a bad API key, a rate limit, a timeout. They fall
+ * through like an unreachable server, so a rate limit can never cost a payer an
+ * objection window. Every other 4xx is cascrow's refusal and is surfaced.
+ */
+const NOT_A_VERDICT_4XX = new Set([401, 408, 429]);
+/** True when prepare's failure is cascrow saying no (a verdict), not cascrow being unavailable. */
+export function isPrepareRefusal(e) {
+    return e instanceof RemoteError && e.status >= 400 && e.status < 500 && !NOT_A_VERDICT_4XX.has(e.status);
+}
+/** The book, read for a NON-book-bound action: a broken book is a loud note, never an abort (post-review H1). */
+function readBookLoosely(ctx, book, notes) {
+    try {
+        return book.read();
+    }
+    catch (e) {
+        if (!(e instanceof SignerError))
+            throw e;
+        const n = `WARNING: the local escrow book could not be used (${e.message}). It was ignored for this action, which is checked against the chain alone; ` +
+            "release and extendDeadline stay refused until the book is restored.";
+        notes.push(n);
+        ctx.io.err(n);
+        return [];
+    }
+}
+export async function escrowAction(ctx, action, input) {
+    const key = await ctx.unlock();
+    const me = key.address;
+    const book = new Book(ctx.home, key.macKey);
+    const bookBound = BOOK_BOUND_ACTIONS.has(action);
+    const notes = [];
+    const c = chainCtx(ctx);
+    // Arguments, computed locally.
+    const reasonHash = action === "object" ? (input.reason ? keccak256(toUtf8Bytes(input.reason)) : refuse("INPUT", "object needs a reason")) : null;
+    const newDeadline = action === "extendDeadline" ? (input.newDeadline !== undefined ? BigInt(input.newDeadline) : refuse("INPUT", "extendDeadline needs newDeadline")) : null;
+    let proofHash = null;
+    if (action === "submitClaim") {
+        if (!input.milestoneId)
+            refuse("INPUT", "submitClaim needs the milestoneId the submission is bound to");
+        const given = input.proofHash?.trim().toLowerCase() ?? null;
+        if (given !== null && !/^0x[0-9a-f]{64}$/.test(given))
+            refuse("INPUT", "proofHash must be 0x + 64 hex characters (the manifestHash the evidence door returned)");
+        const local = hasEvidence(input.evidence) ? localProofHash(input.milestoneId, input.evidence).toLowerCase() : null;
+        if (given && local && given !== local)
+            refuse("INPUT", "the evidence given hashes to a different manifest than proofHash — pass one of them");
+        proofHash = given ?? local ?? refuse("INPUT", "submitClaim needs proofHash (the manifestHash the evidence door returned) or the evidence file(s) to hash locally");
+        // A claim names evidence on chain for good. Only a submission cascrow SEALED has a
+        // verdict; a claim with any other hash gets no recommendation and invites an
+        // objection. So prepare must confirm it — no confirmation, no claim (G2).
+        if (!ctx.remote.configured)
+            refuse("API_KEY_REQUIRED", "submitClaim needs CASCROW_API_KEY: cascrow must confirm the proof hash is a sealed submission of this milestone before it goes on chain");
+    }
+    // Cross-check with cascrow if it answers. Required for submitClaim (above), optional
+    // for every other action: an unreachable cascrow never stops one — but when cascrow
+    // ANSWERS with a refusal, that answer is surfaced, never read as "down" (G1/H2).
+    let prepared = null;
+    if (input.milestoneId && ctx.remote.configured) {
+        try {
+            const raw = await ctx.remote.prepare({
+                milestoneId: input.milestoneId,
+                action,
+                ...(proofHash ? { proofHash } : {}),
+                ...(reasonHash ? { reasonHash } : {}),
+                ...(newDeadline !== null ? { newDeadline: newDeadline.toString() } : {}),
+            });
+            prepared = checkPreparedEnvelope(raw, action, ctx.net, me);
+        }
+        catch (e) {
+            if (e instanceof SignerError)
+                throw e; // prepare answered, and it is wrong: abort
+            if (isPrepareRefusal(e)) {
+                const msg = typeof e.body.error === "string" && e.body.error ? e.body.error : `HTTP ${e.status}`;
+                const detail = refusalDetail(e.body);
+                throw new SignerError(e.code ?? "PREPARE_REFUSED", `cascrow refused to prepare ${action}: ${msg}${detail ? ` — ${detail}` : ""}. Nothing was signed`);
+            }
+            if (action === "submitClaim") {
+                refuse("PREPARE_UNAVAILABLE", `submitClaim needs cascrow to confirm the proof hash is a sealed submission of this milestone, and prepare failed: ${e instanceof Error ? e.message : "error"}. Nothing was signed; retry`);
+            }
+            notes.push(`cascrow's prepare was not available (${e instanceof Error ? e.message : "error"}) — the transaction was built from the chain alone`);
+        }
+    }
+    if (action === "submitClaim" && !prepared)
+        refuse("PREPARE_UNAVAILABLE", "submitClaim needs cascrow's confirmation of the proof hash; nothing was signed");
+    // Only a book-bound action reads the book strictly (a broken book refuses it); any
+    // other action reads it, if at all, loosely — to find an escrow ID or a milestone.
+    const lookup = () => (bookBound ? book.read() : readBookLoosely(ctx, book, notes));
+    let escrowId = input.escrowId?.toLowerCase() ?? null;
+    if (!escrowId && input.milestoneId) {
+        escrowId = lookup().find((e) => e.milestoneId === input.milestoneId && e.chainId === ctx.net.chainId && e.contract === ctx.net.address.toLowerCase())?.escrowId ?? null;
+    }
+    if (!escrowId && prepared)
+        escrowId = prepared.escrowId.toLowerCase();
+    if (!escrowId || !/^0x[0-9a-f]{64}$/.test(escrowId))
+        refuse("INPUT", "no escrowId: pass it, or a milestoneId this signer has in its book");
+    if (prepared && prepared.escrowId.toLowerCase() !== escrowId)
+        refuse("PREPARE_DISAGREES", "prepare names a different escrow than the one asked for");
+    const args = action === "object" ? [escrowId, reasonHash] :
+        action === "extendDeadline" ? [escrowId, newDeadline.toString()] :
+            action === "submitClaim" ? [escrowId, proofHash] :
+                [escrowId];
+    const data = encodeCall(action, args);
+    if (prepared)
+        checkMatchesLocal({ to: ctx.net.address, data, value: BigInt(0) }, prepared);
+    return withLock(ctx.home, async () => {
+        await verifyEndpoint(ctx.rpc, ctx.net);
+        const head = await latestBlock(c);
+        const e = await readEscrow(c, escrowId);
+        const findIn = (entries) => entries.find((x) => x.escrowId === escrowId && x.chainId === ctx.net.chainId && x.contract === ctx.net.address.toLowerCase()) ?? null;
+        const entry = bookBound ? book.find(escrowId, ctx.net.chainId, ctx.net.address) : input.milestoneId ? null : findIn(readBookLoosely(ctx, book, notes));
+        checkEscrowAction(action, me, e, head.timestamp, { book: entry, newDeadline, proofHash, reasonHash });
+        const rid = ctx.journal.exists() ? ctx.journal.reserve(action, escrowId, BigInt(0), head.timestamp) : (ctx.journal.create(true), ctx.journal.reserve(action, escrowId, BigInt(0), head.timestamp));
+        const sent = await sendSigned(c, key, ctx.journal, rid, { to: ctx.net.address, data, value: BigInt(0) });
+        if (sent.note)
+            notes.push(sent.note);
+        const milestoneId = input.milestoneId ?? entry?.milestoneId ?? null;
+        const reported = await report(ctx, milestoneId, sent.txHash, notes);
+        return {
+            action,
+            escrowId,
+            txHash: sent.txHash,
+            sent: sent.sent,
+            reported,
+            from: me,
+            ...(proofHash ? { proofHash } : {}),
+            ...(reasonHash ? { reasonHash } : {}),
+            notes,
+        };
+    });
+}
+/** withdraw(own account, native XRP): pays this key's credit to this key. No escrow, no cascrow. */
+export async function withdraw(ctx) {
+    const key = await ctx.unlock();
+    const me = getAddress(key.address);
+    const c = chainCtx(ctx);
+    const notes = [];
+    return withLock(ctx.home, async () => {
+        await verifyEndpoint(ctx.rpc, ctx.net);
+        const head = await latestBlock(c);
+        const credit = await readCredit(c, me);
+        checkWithdraw(me, credit);
+        if (!ctx.journal.exists())
+            ctx.journal.create(true);
+        const rid = ctx.journal.reserve("withdraw", null, BigInt(0), head.timestamp);
+        const data = encodeCall("withdraw", [me, "0x0000000000000000000000000000000000000000"]);
+        const sent = await sendSigned(c, key, ctx.journal, rid, { to: ctx.net.address, data, value: BigInt(0) });
+        if (sent.note)
+            notes.push(sent.note);
+        return { action: "withdraw", escrowId: "", txHash: sent.txHash, sent: sent.sent, reported: false, from: me, creditWei: credit.toString(), notes };
+    });
+}
+export { PER_ESCROW_ACTIONS };

package/dist/api.d.ts

@@ -0,0 +1,83 @@
+import { SignerContext } from "./context.js";
+import type { Io, SignerConfig } from "./context.js";
+import type { PolicyInput } from "./policy.js";
+import type { EscrowActionInput, FundInput } from "./actions.js";
+import type { AcceptInput } from "./acceptance.js";
+import type { WatchOptions } from "./watch.js";
+export { SignerError } from "./errors.js";
+export { SignerContext } from "./context.js";
+export type { Io, SignerConfig } from "./context.js";
+export { LOCAL_ONLY_TOOLS } from "./tools.js";
+export { checkAcceptance } from "./acceptance.js";
+export { checkChallenge, CHALLENGE_PREFIX } from "./link.js";
+export { localProofHash } from "./actions.js";
+export { resolveNetwork, PUBLIC_NETWORKS } from "./network.js";
+export declare const SIGNER_VERSION = "0.1.0";
+/** Create the keystore and the spending journal. Does not need a network or cascrow. */
+export declare function initSigner(home: string, passphrase: string, opts?: {
+    scryptN?: number;
+}): Promise<{
+    address: string;
+    home: string;
+}>;
+type Env = Record<string, string | undefined>;
+export declare function configFromEnv(env: Env, io: Io, overrides?: Partial<SignerConfig>): SignerConfig;
+export declare function createSigner(cfg: SignerConfig): {
+    ctx: SignerContext;
+    address: () => string;
+    link: () => Promise<{
+        linked: boolean;
+        walletAddress: string;
+        changed: boolean;
+        message: string;
+    } | {
+        linked: boolean;
+        walletAddress: string;
+        changed: boolean;
+        message?: undefined;
+    }>;
+    accept: (i: AcceptInput) => Promise<{
+        accepted: boolean;
+        escrowId: string;
+        payer: string;
+        amountWei: string;
+        acceptBy: string;
+        deadline: string;
+        reviewPeriod: number;
+        arbiter: string;
+        server: {
+            escrowId: {} | null;
+            acceptBy: {} | null;
+        };
+        note: string;
+    }>;
+    fund: (i: FundInput) => Promise<import("./actions.js").ActionResult>;
+    submitClaim: (i: EscrowActionInput) => Promise<import("./actions.js").ActionResult>;
+    claim: (i: EscrowActionInput) => Promise<import("./actions.js").ActionResult>;
+    release: (i: EscrowActionInput) => Promise<import("./actions.js").ActionResult>;
+    object: (i: EscrowActionInput) => Promise<import("./actions.js").ActionResult>;
+    refund: (i: EscrowActionInput) => Promise<import("./actions.js").ActionResult>;
+    extendDeadline: (i: EscrowActionInput) => Promise<import("./actions.js").ActionResult>;
+    returnFunds: (i: EscrowActionInput) => Promise<import("./actions.js").ActionResult>;
+    withdraw: () => Promise<import("./actions.js").ActionResult>;
+    onchainClaims: () => Promise<{
+        address: string;
+        claims: import("./watch.js").OnchainClaim[];
+        escrowsChecked: number;
+    }>;
+    watch: (o?: WatchOptions) => Promise<void>;
+    speedUp: (txHash: string) => Promise<import("./chain.js").SendResult>;
+    policy: () => Promise<import("./policy.js").Policy>;
+    setPolicy: (input: PolicyInput) => Promise<import("./policy.js").Policy>;
+    status: () => {
+        address: string;
+        network: import("./network.js").SignerNetworkName;
+        chainId: number;
+        contract: string;
+        rpcUrl: string;
+        overridden: boolean;
+        home: string;
+        version: string;
+    };
+};
+export type Signer = ReturnType<typeof createSigner>;

package/dist/api.js

@@ -0,0 +1,105 @@
+/**
+ * cascrow-signer — the programmatic API.
+ *
+ * Everything the CLI and the MCP server do goes through here. The key lives in
+ * an encrypted keystore on this machine (keystore.ts) and never leaves it; the
+ * only things sent to cascrow are listed in remote.ts, and every transaction goes
+ * to the pinned public RPC of the network (network.ts).
+ *
+ *   import { createSigner, configFromEnv } from "cascrow-signer";
+ *   const s = createSigner(configFromEnv(process.env, io));
+ *   await s.object({ escrowId, reason: "The delivery does not meet criterion 2." });
+ */
+import { refuse } from "./errors.js";
+import { SignerContext } from "./context.js";
+import { createKeystore } from "./keystore.js";
+import { Journal } from "./journal.js";
+import { buildPolicy, loadPolicy, savePolicy } from "./policy.js";
+import { escrowAction, fund, withdraw } from "./actions.js";
+import { accept } from "./acceptance.js";
+import { link } from "./link.js";
+import { onchainClaims, watch } from "./watch.js";
+import { speedUp } from "./chain.js";
+import { withLock } from "./journal.js";
+import { ensureHome, signerHome } from "./files.js";
+export { SignerError } from "./errors.js";
+export { SignerContext } from "./context.js";
+export { LOCAL_ONLY_TOOLS } from "./tools.js";
+export { checkAcceptance } from "./acceptance.js";
+export { checkChallenge, CHALLENGE_PREFIX } from "./link.js";
+export { localProofHash } from "./actions.js";
+export { resolveNetwork, PUBLIC_NETWORKS } from "./network.js";
+export const SIGNER_VERSION = "0.1.0";
+/** Create the keystore and the spending journal. Does not need a network or cascrow. */
+export async function initSigner(home, passphrase, opts = {}) {
+    ensureHome(home);
+    const { address } = await createKeystore(home, passphrase, opts);
+    new Journal(home).create();
+    return { address, home };
+}
+export function configFromEnv(env, io, overrides = {}) {
+    const network = (overrides.network ?? env.CASCROW_SIGNER_NETWORK ?? "").trim();
+    if (network !== "testnet" && network !== "mainnet") {
+        refuse("NETWORK_REQUIRED", "name the network: --network testnet|mainnet or CASCROW_SIGNER_NETWORK (the signer never guesses a chain)");
+    }
+    const o = {
+        rpcUrl: env.CASCROW_SIGNER_TESTNET_RPC_URL || undefined,
+        address: env.CASCROW_SIGNER_TESTNET_CONTRACT || undefined,
+        deployBlock: env.CASCROW_SIGNER_TESTNET_DEPLOY_BLOCK ? Number(env.CASCROW_SIGNER_TESTNET_DEPLOY_BLOCK) : undefined,
+        runtimeCodeHash: env.CASCROW_SIGNER_TESTNET_CODE_HASH || undefined,
+    };
+    return {
+        home: overrides.home ?? signerHome(env),
+        network,
+        override: overrides.override ?? o,
+        apiBaseUrl: overrides.apiBaseUrl ?? env.CASCROW_BASE_URL ?? "https://cascrow.com",
+        apiKey: overrides.apiKey ?? env.CASCROW_API_KEY ?? "",
+        io,
+        ...(overrides.passphrase ? { passphrase: overrides.passphrase } : {}),
+    };
+}
+export function createSigner(cfg) {
+    const ctx = new SignerContext(cfg);
+    const act = (a) => (i) => escrowAction(ctx, a, i);
+    return {
+        ctx,
+        address: () => ctx.address(),
+        link: () => link(ctx),
+        accept: (i) => accept(ctx, i),
+        fund: (i) => fund(ctx, i),
+        submitClaim: act("submitClaim"),
+        claim: act("claim"),
+        release: act("release"),
+        object: act("object"),
+        refund: act("refund"),
+        extendDeadline: act("extendDeadline"),
+        returnFunds: act("returnFunds"),
+        withdraw: () => withdraw(ctx),
+        onchainClaims: () => onchainClaims(ctx),
+        watch: (o) => watch(ctx, o),
+        speedUp: async (txHash) => {
+            const key = await ctx.unlock();
+            return withLock(ctx.home, () => speedUp({ rpc: ctx.rpc, net: ctx.net }, key, ctx.journal, txHash));
+        },
+        policy: async () => {
+            const key = await ctx.unlock();
+            return loadPolicy(ctx.home, key.macKey, key.address);
+        },
+        setPolicy: async (input) => {
+            const key = await ctx.unlock();
+            const p = buildPolicy(key.address, input);
+            savePolicy(ctx.home, key.macKey, p, ctx.io);
+            return p;
+        },
+        status: () => ({
+            address: ctx.address(),
+            network: ctx.net.name,
+            chainId: ctx.net.chainId,
+            contract: ctx.net.address,
+            rpcUrl: ctx.net.rpcUrl,
+            overridden: ctx.net.overridden,
+            home: ctx.home,
+            version: SIGNER_VERSION,
+        }),
+    };
+}

package/dist/book.d.ts

@@ -0,0 +1,26 @@
+export declare const BOOK_FILE = "escrows.json";
+export type BookEntry = {
+    escrowId: string;
+    role: "payer" | "payee";
+    milestoneId: string | null;
+    payer: string;
+    payee: string;
+    amountWei: string;
+    chainId: number;
+    contract: string;
+    at: number;
+};
+export declare class Book {
+    private readonly home;
+    private readonly macKey;
+    private readonly file;
+    constructor(home: string, macKey: Buffer);
+    read(): BookEntry[];
+    find(escrowId: string, chainId: number, contract: string): BookEntry | null;
+    add(e: Omit<BookEntry, "escrowId" | "payer" | "payee" | "contract"> & {
+        escrowId: string;
+        payer: string;
+        payee: string;
+        contract: string;
+    }): void;
+}

package/dist/book.js

@@ -0,0 +1,62 @@
+/**
+ * The local escrow book: every escrow this key funded (as payer) or accepted (as
+ * payee), written at the moment it signed — never learned from cascrow.
+ *
+ * `release`, `object` and `extendDeadline` are only signed for an escrow in the
+ * book whose ON-CHAIN payer is this key and whose on-chain payee is the book's.
+ * The watcher (watch.ts) reads its escrows from here and from the chain, so a
+ * server that "forgets" an escrow cannot hide a claim from its payer.
+ *
+ * MAC'd like the policy (same derived key), so an entry cannot be slipped in by a
+ * process that can write the directory but not unlock the key.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getAddress } from "ethers";
+import { refuse } from "./errors.js";
+import { ensureHome, macMatches, macOf, readPrivateFile, replacePrivateFile } from "./files.js";
+export const BOOK_FILE = "escrows.json";
+export class Book {
+    home;
+    macKey;
+    file;
+    constructor(home, macKey) {
+        this.home = home;
+        this.macKey = macKey;
+        this.file = path.join(home, BOOK_FILE);
+    }
+    read() {
+        ensureHome(this.home);
+        if (!fs.existsSync(this.file))
+            return [];
+        let parsed;
+        try {
+            parsed = JSON.parse(readPrivateFile(this.file));
+        }
+        catch {
+            refuse("BOOK_TAMPERED", "the local escrow book is not valid JSON");
+        }
+        if (!Array.isArray(parsed.entries) || !macMatches(this.macKey, parsed.entries, parsed.mac)) {
+            refuse("BOOK_TAMPERED", "the local escrow book was changed outside the signer — it is not used");
+        }
+        return parsed.entries;
+    }
+    find(escrowId, chainId, contract) {
+        const id = escrowId.toLowerCase();
+        return this.read().find((e) => e.escrowId === id && e.chainId === chainId && e.contract === contract.toLowerCase()) ?? null;
+    }
+    add(e) {
+        const entries = this.read();
+        const norm = {
+            ...e,
+            escrowId: e.escrowId.toLowerCase(),
+            payer: getAddress(e.payer).toLowerCase(),
+            payee: getAddress(e.payee).toLowerCase(),
+            contract: getAddress(e.contract).toLowerCase(),
+        };
+        if (entries.some((x) => x.escrowId === norm.escrowId && x.chainId === norm.chainId && x.contract === norm.contract))
+            return;
+        entries.push(norm);
+        replacePrivateFile(this.file, JSON.stringify({ entries, mac: macOf(this.macKey, entries) }, null, 2));
+    }
+}

package/dist/calldata.d.ts

@@ -0,0 +1,62 @@
+import { Interface } from "ethers";
+import type { TypedDataDomain, TypedDataField } from "ethers";
+export declare const ESCROW_V3_INTERFACE: Interface;
+export declare const V3_PHASE_NAMES: readonly string[];
+export declare const V3_LIMITS: Readonly<{
+    MIN_REVIEW_SECONDS: number;
+    MAX_REVIEW_SECONDS: number;
+    MIN_ARBITRATION_SECONDS: number;
+    MAX_ARBITRATION_SECONDS: number;
+    MAX_DEADLINE_SECONDS: number;
+    MAX_CLAIMS: number;
+}>;
+export declare const ACCEPTANCE_TYPES: Record<string, TypedDataField[]>;
+export declare const ACCEPTANCE_PRIMARY_TYPE: string;
+/** keccak256(abi.encode(payer, ref, salt)) — the contract's `escrowIdFor`. */
+export declare function escrowIdFor(payer: string, ref: string, salt: string): string;
+/** The domain a payee signs under — the PINNED chain and contract, never the server's. */
+export declare function acceptanceDomain(chainId: number, verifyingContract: string): TypedDataDomain;
+/** The contract function each action calls. `resolve` is the arbiter's and is not offered. */
+export declare const ACTION_FN: Readonly<{
+    readonly fund: "fund";
+    readonly submitClaim: "submitClaim";
+    readonly claim: "claim";
+    readonly release: "release";
+    readonly object: "object";
+    readonly refund: "refund";
+    readonly extendDeadline: "extendDeadline";
+    readonly returnFunds: "returnFunds";
+    readonly withdraw: "withdraw";
+}>;
+export type SignerAction = keyof typeof ACTION_FN;
+export declare const SIGNER_ACTIONS: readonly ("object" | "fund" | "submitClaim" | "claim" | "release" | "refund" | "extendDeadline" | "returnFunds" | "withdraw")[];
+/** Actions whose first argument is the escrow ID. */
+export declare const PER_ESCROW_ACTIONS: ReadonlySet<SignerAction>;
+/** Canonical form of `args` for `fn`, whatever shape (ethers Result, strings, bigints) they come in. */
+export declare function canonicalArgs(fn: string, args: readonly unknown[]): unknown[];
+/** Calldata for `fn(args)`, encoded from the pinned ABI. */
+export declare function encodeCall(fn: string, args: readonly unknown[]): string;
+/** Decode calldata into its function name and canonical arguments. */
+export declare function decodeCall(data: string): {
+    fn: string;
+    args: unknown[];
+};
+export declare function sameCanonical(a: unknown, b: unknown): boolean;
+export declare const ZERO_ADDRESS: string;
+/** The escrow as `getEscrow` returns it, with numbers as bigint/number. */
+export type ChainEscrow = {
+    payer: string;
+    deadline: number;
+    reviewPeriod: number;
+    payee: string;
+    claimedAt: number;
+    claimCount: number;
+    objected: boolean;
+    status: number;
+    arbiter: string;
+    objectedAt: number;
+    arbitrationPeriod: number;
+    token: string;
+    amount: bigint;
+};
+export declare function decodeGetEscrow(result: string): ChainEscrow;