cascrow-signer 0.1.0

package/dist/tools.js

@@ -0,0 +1,112 @@
+const escrowRef = {
+    escrowId: { type: "string", description: "The escrow ID (0x…). Optional when milestoneId names an escrow in this signer's local book." },
+    milestoneId: { type: "string", description: "The cascrow milestone. Used to find the escrow in the local book and to report the transaction hash." },
+};
+export const SIGNER_TOOLS = Object.freeze([
+    {
+        name: "cascrow_signer_status",
+        description: "Show this local signer's address, network, pinned escrow contract and RPC. Signs nothing.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "cascrow_signer_link",
+        description: "Link this signer's address to your cascrow account by signing cascrow's wallet-ownership challenge (only that exact sentence is ever signed). " +
+            "Refuses to replace a different linked wallet — that needs a person on a terminal: cascrow-signer link.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "cascrow_signer_accept",
+        description: "As the PAYEE, check the payer's MilestoneEscrowV3 offer against this signer's pinned chain and contract and sign the acceptance locally. " +
+            "The signature is binding until acceptBy: the payer can fund these exact terms until then. Refuses an offer whose payee is not this key, whose token is not native XRP, " +
+            "whose arbiter your local policy does not accept, or whose acceptBy has passed on chain.",
+        inputSchema: {
+            type: "object",
+            required: ["milestoneId"],
+            properties: {
+                milestoneId: { type: "string" },
+                minAmountXrp: { type: "string", description: "Refuse if the escrowed amount is below this many XRP." },
+            },
+        },
+    },
+    {
+        name: "cascrow_signer_fund",
+        description: "As the PAYER, fund an accepted MilestoneEscrowV3 escrow with ONE transaction (value = amount, no approve). The signer rebuilds and checks every term " +
+            "(escrow ID from your own address, native XRP, your per-escrow and 24-hour limits, arbiter, review period, the payee's signature under the pinned domain, acceptBy on chain time) " +
+            "and sends to the public RPC itself. Limits are set only on a terminal: cascrow-signer policy set.",
+        inputSchema: {
+            type: "object",
+            required: ["milestoneId"],
+            properties: {
+                milestoneId: { type: "string" },
+                maxAmountXrp: { type: "string", description: "Refuse if the amount exceeds this many XRP (on top of the local limits)." },
+            },
+        },
+    },
+    {
+        name: "cascrow_signer_submit_claim",
+        description: "As the PAYEE, claim the escrow on chain with ONE sealed submission. Pass proofHash = the manifestHash the evidence door returned " +
+            "(cascrow_mcp_submit, proof upload, cascrow_verify_work) — one submission is one evidence request (today one file, text or GitHub item). " +
+            "Alternatively pass the one file (or text) of that submission and the hash is computed HERE. Either way cascrow must confirm the hash is a " +
+            "sealed submission of this milestone before anything is signed (CLAIM_PROOF_UNKNOWN otherwise). Claim with a submission whose verdict is YES " +
+            "(claimReady) — with NO or PENDING the payer is likely to object. The payer then has the review period to object.",
+        inputSchema: {
+            type: "object",
+            required: ["milestoneId"],
+            properties: {
+                ...escrowRef,
+                proofHash: { type: "string", description: "The manifestHash the evidence door returned for the sealed submission (0x + 64 hex)." },
+                files: { type: "array", items: { type: "string" }, description: "Instead of proofHash: the path of the submission's file." },
+                texts: { type: "array", items: { type: "string" }, description: "Instead of proofHash: the submission's text, byte for byte as the evidence door received it." },
+            },
+        },
+    },
+    {
+        name: "cascrow_signer_object",
+        description: "As the PAYER, object to the live claim before its objection deadline — this stops the release. Only for escrows whose on-chain payer is this key " +
+            "(read from the chain; the local book is not needed). cascrow's server is not needed; the transaction is built from the chain. If the objection is pending too long, use cascrow_signer_speed_up.",
+        inputSchema: { type: "object", required: ["reason"], properties: { ...escrowRef, reason: { type: "string", description: "Why; its keccak256 goes on chain." } } },
+    },
+    {
+        name: "cascrow_signer_release",
+        description: "As the PAYER, pay the escrow to the payee now. Only for escrows this signer funded, whose on-chain payee is the one in the local book.",
+        inputSchema: { type: "object", properties: { ...escrowRef } },
+    },
+    {
+        name: "cascrow_signer_extend_deadline",
+        description: "As the PAYER, move the escrow's deadline later (never earlier). Only for escrows this signer funded.",
+        inputSchema: { type: "object", required: ["newDeadline"], properties: { ...escrowRef, newDeadline: { type: "string", description: "Unix seconds." } } },
+    },
+    {
+        name: "cascrow_signer_claim",
+        description: "Pay out a claim whose objection window has closed without an objection (either party may call it).",
+        inputSchema: { type: "object", properties: { ...escrowRef } },
+    },
+    {
+        name: "cascrow_signer_refund",
+        description: "Return the escrow to the payer once the contract allows it (deadline passed with no live claim, or an arbitration window lapsed).",
+        inputSchema: { type: "object", properties: { ...escrowRef } },
+    },
+    {
+        name: "cascrow_signer_return_funds",
+        description: "As the PAYEE, give the escrowed money back to the payer.",
+        inputSchema: { type: "object", properties: { ...escrowRef } },
+    },
+    {
+        name: "cascrow_signer_withdraw",
+        description: "Withdraw this address's own credit from the escrow contract (a payment that could not be pushed). Pays only this address.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "cascrow_signer_onchain_claims",
+        description: "As the PAYER, list the live claims on your escrows read from the CHAIN (your Funded events and local journal) — not from cascrow. " +
+            "Every entry with objectable=true releases your money at objectionDeadline unless you object.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "cascrow_signer_speed_up",
+        description: "Replace one of this signer's pending transactions with the same nonce and a 25% higher fee.",
+        inputSchema: { type: "object", required: ["txHash"], properties: { txHash: { type: "string" } } },
+    },
+]);
+/** The tools only this package offers — disjoint from the hosted cascrow MCP tools. */
+export const LOCAL_ONLY_TOOLS = Object.freeze(SIGNER_TOOLS.map((t) => t.name));

package/dist/watch.d.ts

@@ -0,0 +1,35 @@
+import type { ChainCtx } from "./chain.js";
+import type { SignerContext } from "./context.js";
+export type OnchainClaim = {
+    escrowId: string;
+    role: "payer";
+    claimIndex: number;
+    claimedAt: number;
+    objectionDeadline: number;
+    secondsLeft: number;
+    objectable: boolean;
+};
+/** Every escrow this address funded, from Funded(payer = me) since the deploy block. */
+export declare function escrowsFundedBy(c: ChainCtx, me: string, toBlock: number): Promise<string[]>;
+/** Open claims on this address's escrows, read from the chain alone. */
+export declare function onchainClaims(ctx: SignerContext): Promise<{
+    address: string;
+    claims: OnchainClaim[];
+    escrowsChecked: number;
+}>;
+/**
+ * The environment an `--exec` alarm command gets: an allowlist of what a program
+ * needs to start (PATH, HOME, locale, temp dir, and the Windows basics) plus the
+ * claim — never the signer's own environment, which may carry the API key or,
+ * in a caller that set it, the keystore passphrase (post-review H3).
+ */
+export declare const EXEC_ENV_ALLOWLIST: readonly string[];
+export declare function execEnv(env: Record<string, string | undefined>, cl: Pick<OnchainClaim, "escrowId" | "claimIndex" | "objectionDeadline">): Record<string, string>;
+export type WatchOptions = {
+    intervalSec?: number;
+    exec?: string;
+    webhook?: string;
+    once?: boolean;
+    signal?: AbortSignal;
+};
+export declare function watch(ctx: SignerContext, o?: WatchOptions): Promise<void>;

package/dist/watch.js

@@ -0,0 +1,129 @@
+/**
+ * The payer's watcher: finds this key's escrows ON CHAIN (every `Funded` event
+ * with payer = this address, plus the escrows in the local journal) and raises
+ * an alarm for every live claim whose objection window is still open.
+ *
+ * Never from cascrow. The objection window can be one hour long, and a veto with
+ * a clock must not depend on the index, the notifications or the reachability of
+ * the party that is not the payer. It needs no passphrase: it reads the address
+ * from the keystore file and signs nothing.
+ *
+ * Alarms go to stderr, to an optional `--exec` command (run without a shell,
+ * with an allowlisted environment plus the claim — `execEnv`) and to an optional webhook of the
+ * user's own. The remedy it names is the payer's own `object`; if an objection is
+ * already pending, raise its fee (`cascrow-signer speed-up`) instead of waiting.
+ */
+import { execFile } from "node:child_process";
+import { toBeHex, zeroPadValue, getAddress } from "ethers";
+import { ESCROW_V3_INTERFACE } from "./calldata.js";
+import { latestBlock, readEscrow } from "./chain.js";
+import { chainFacts } from "./checks.js";
+import { v3ClaimLive, v3ObjectionDeadline } from "./generated/v3-actions.js";
+import { verifyEndpoint } from "./network.js";
+const LOG_CHUNK = 10_000;
+/** Every escrow this address funded, from Funded(payer = me) since the deploy block. */
+export async function escrowsFundedBy(c, me, toBlock) {
+    const topic0 = ESCROW_V3_INTERFACE.getEvent("Funded").topicHash;
+    const payerTopic = zeroPadValue(getAddress(me), 32).toLowerCase();
+    const ids = new Set();
+    for (let start = c.net.deployBlock; start <= toBlock; start += LOG_CHUNK) {
+        const end = Math.min(toBlock, start + LOG_CHUNK - 1);
+        const logs = await c.rpc.call("eth_getLogs", [
+            { address: c.net.address, fromBlock: toBeHex(start), toBlock: toBeHex(end), topics: [topic0, null, payerTopic] },
+        ]);
+        for (const l of logs ?? []) {
+            const p = ESCROW_V3_INTERFACE.parseLog(l);
+            if (p && p.name === "Funded")
+                ids.add(String(p.args.escrowId).toLowerCase());
+        }
+    }
+    return [...ids];
+}
+/** Open claims on this address's escrows, read from the chain alone. */
+export async function onchainClaims(ctx) {
+    const me = getAddress(ctx.address());
+    const c = { rpc: ctx.rpc, net: ctx.net };
+    await verifyEndpoint(ctx.rpc, ctx.net);
+    const head = await latestBlock(c);
+    const ids = new Set(await escrowsFundedBy(c, me, head.number));
+    for (const r of ctx.journal.exists() ? ctx.journal.read() : [])
+        if (r.action === "fund" && r.escrowId)
+            ids.add(r.escrowId.toLowerCase());
+    const claims = [];
+    for (const id of ids) {
+        const e = await readEscrow(c, id);
+        if (e.status !== 1 || e.payer !== me)
+            continue;
+        const f = chainFacts(e);
+        if (!v3ClaimLive(f))
+            continue;
+        const deadline = v3ObjectionDeadline(f);
+        claims.push({
+            escrowId: id,
+            role: "payer",
+            claimIndex: e.claimCount,
+            claimedAt: e.claimedAt,
+            objectionDeadline: deadline,
+            secondsLeft: Math.max(0, deadline - head.timestamp),
+            objectable: head.timestamp < deadline,
+        });
+    }
+    return { address: me, claims, escrowsChecked: ids.size };
+}
+function fmtLeft(s) {
+    const h = Math.floor(s / 3600);
+    const m = Math.floor((s % 3600) / 60);
+    return `${h}h ${m}m`;
+}
+/**
+ * The environment an `--exec` alarm command gets: an allowlist of what a program
+ * needs to start (PATH, HOME, locale, temp dir, and the Windows basics) plus the
+ * claim — never the signer's own environment, which may carry the API key or,
+ * in a caller that set it, the keystore passphrase (post-review H3).
+ */
+export const EXEC_ENV_ALLOWLIST = Object.freeze([
+    "PATH", "HOME", "USER", "LOGNAME", "SHELL", "LANG", "LC_ALL", "LC_CTYPE", "TZ", "TMPDIR", "TEMP", "TMP",
+    "SYSTEMROOT", "SYSTEMDRIVE", "WINDIR", "COMSPEC", "PATHEXT", "USERPROFILE",
+]);
+export function execEnv(env, cl) {
+    const out = {};
+    for (const k of EXEC_ENV_ALLOWLIST)
+        if (typeof env[k] === "string")
+            out[k] = env[k];
+    out.CASCROW_ESCROW_ID = cl.escrowId;
+    out.CASCROW_CLAIM_INDEX = String(cl.claimIndex);
+    out.CASCROW_OBJECTION_DEADLINE = String(cl.objectionDeadline);
+    return out;
+}
+export async function watch(ctx, o = {}) {
+    const seen = new Set();
+    const interval = Math.max(15, o.intervalSec ?? 60) * 1000;
+    for (;;) {
+        try {
+            const { claims } = await onchainClaims(ctx);
+            for (const cl of claims) {
+                if (!cl.objectable)
+                    continue;
+                const k = `${cl.escrowId}:${cl.claimedAt}`;
+                if (seen.has(k))
+                    continue;
+                seen.add(k);
+                ctx.io.err(`ALARM: claim #${cl.claimIndex} on escrow ${cl.escrowId} releases your money in ${fmtLeft(cl.secondsLeft)} ` +
+                    `(at ${new Date(cl.objectionDeadline * 1000).toISOString()}) unless you object: cascrow-signer object --escrow ${cl.escrowId} --reason "…". ` +
+                    "If an objection is already pending, raise its fee: cascrow-signer speed-up --tx <hash>.");
+                if (o.exec) {
+                    execFile(o.exec, [], { env: execEnv(process.env, cl) }, () => undefined);
+                }
+                if (o.webhook) {
+                    fetch(o.webhook, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ type: "claim.open", ...cl }) }).catch(() => undefined);
+                }
+            }
+        }
+        catch (e) {
+            ctx.io.err(`watch: could not read the chain (${e instanceof Error ? e.message : "error"}) — retrying. Your objection window runs regardless.`);
+        }
+        if (o.once || o.signal?.aborted)
+            return;
+        await new Promise((r) => setTimeout(r, interval));
+    }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "cascrow-signer",
+  "version": "0.1.0",
+  "description": "Local signer for cascrow MilestoneEscrowV3 escrows — your key is generated, encrypted and used only on your machine; cascrow prepares, you check and sign",
+  "type": "module",
+  "main": "./dist/api.js",
+  "types": "./dist/api.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/api.d.ts",
+      "import": "./dist/api.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "cascrow-signer": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SECURITY.md",
+    "MIGRATION.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node build-copy.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ethers": "6.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "20.19.37",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "cascrow",
+    "escrow",
+    "signer",
+    "xrpl-evm",
+    "milestone",
+    "agent",
+    "verification",
+    "trust"
+  ],
+  "author": "Cascrow <dev@cascrow.com>",
+  "license": "MIT",
+  "homepage": "https://cascrow.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jnm04/Milestone-Based-Funding.git",
+    "directory": "cascrow-signer"
+  },
+  "bugs": {
+    "url": "https://github.com/Jnm04/Milestone-Based-Funding/issues"
+  }
+}