@blockula/mcp 0.5.1 → 1.0.0

package/dist/locks.d.ts

@@ -0,0 +1,61 @@
+export interface LockOptions {
+    /** A lock file not touched for this long is a stuck holder's, and is taken over. */
+    staleMs: number;
+    /** How long to wait for the lock before giving up. */
+    waitMs: number;
+    pollMs: number;
+    /** How often a live holder touches its lock file, so a slow call isn't taken over as stuck (default a quarter of `staleMs`). */
+    refreshMs?: number;
+}
+export declare class AccountLocks {
+    readonly dir: string;
+    readonly opts: LockOptions;
+    private readonly queues;
+    constructor(dir: string, opts?: LockOptions);
+    /** The lock file for a key (`<chain_id> <genesis_hash> <address>`). */
+    file(key: string): string;
+    /** Runs `f` holding `key`'s lock: no other call in this process, or other process sharing the directory, holds it meanwhile. */
+    run<T>(key: string, f: () => Promise<T>): Promise<T>;
+    private holdingFile;
+    /**
+     * Removes `lock`, which was read as `seen` and judged dead or stuck. Several waiters can judge
+     * the same lock at once, and the first one's takeover lets another process create a fresh lock
+     * before the second one's removal: deleting by name would then delete that fresh lock, and two
+     * holders would work on one account. So the lock is renamed to a name of this takeover's own
+     * (only one rename of it succeeds, and a lock that's gone throws ENOENT: nothing to do), and
+     * deleted only if what was moved is `seen`. If it's another lock, it's put back, unless a third
+     * process has already made a new one (then nothing can undo that; the window is the few calls
+     * between the rename and the link).
+     */
+    protected takeOver(lock: string, seen: string): void;
+}
+/**
+ * One small file per (chain, account), beside its lock: every write to it happens while holding
+ * that account's AccountLocks lock, so two processes never write it at once.
+ *
+ * A node's next_nonce can lag what this MCP knows: its mempool may not show a tx another node
+ * took, and right after a block runs its account read can still be the one before (observed on a
+ * dev chain: "bad nonce: expected 5, got 4" for the tx after a finalized one). Nonces only go up,
+ * so a tx that ran keeps its nonce spent for good, and a pending one holds its nonce until its
+ * valid_until. One that was dropped or refused holds nothing: its nonce may be free again.
+ */
+export declare class NonceTracker {
+    readonly dir: string;
+    constructor(dir: string);
+    file(key: string): string;
+    private read;
+    private write;
+    /** The lowest nonce the next tx may take: past the last one that ran, and past a pending one while it can still run (the chain at or before its valid_until). */
+    floor(key: string, height: number): number | undefined;
+    /** A tx was submitted and isn't final yet. Call holding the account's lock. */
+    pending(key: string, nonce: number, validUntil: number): void;
+    /** The tx with this nonce ran in a block (finalized, or failed: its fee was charged). Call holding the account's lock. */
+    ran(key: string, nonce: number): void;
+    /**
+     * Forgets what's known: after the node refused a tx for a nonce past its own, so a wrong record
+     * (a node that said a tx ran when it didn't) can't block every later tx. Call holding the lock.
+     */
+    forget(key: string): void;
+    /** The tx with this nonce was dropped or refused: it holds its nonce no longer. Call holding the account's lock. */
+    settled(key: string, nonce: number): void;
+}

package/dist/locks.js

@@ -0,0 +1,222 @@
+// One tx at a time per account (AGENT-10). A tx's nonce is the node's `next_nonce` when it's built,
+// so two built before either reaches the node get the same nonce, and the node refuses one ("bad
+// nonce"). That happened with parallel tool calls in one session and with two sessions at once.
+//
+// - AccountLocks serializes building, signing and submitting per account: in this process with a
+//   promise chain, and across processes sharing BLOCKULA_HOME with a lock file (spend.ts's
+//   pattern, made asynchronous: a request to the node can take seconds). Waiting for finality
+//   happens outside the lock, so parallel sends still overlap there. A live holder touches its
+//   lock file while it works (`LockOptions.refreshMs`), so only a holder that's gone, or hung past
+//   `staleMs`, has its lock taken over; and a takeover moves the lock aside under a name of its own
+//   before it deletes it, and puts back a lock it moved by mistake (`takeOver`).
+// - NonceTracker remembers the last nonce this MCP signed per (chain, account) while its tx is
+//   pending (submitted, not yet final). The next tx takes max(node next_nonce, last + 1), so a node
+//   whose view lags the mempool that took the last one can't hand out its nonce again. It only
+//   informs: an unreadable file means the node's next_nonce, as before.
+import { createHash } from "node:crypto";
+import { mkdirSync, openSync, closeSync, linkSync, readFileSync, renameSync, rmSync, statSync, utimesSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Whether a process with this pid is running (on this machine). */
+function alive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+export class AccountLocks {
+    dir;
+    opts;
+    queues = new Map();
+    constructor(dir, opts = { staleMs: 120_000, waitMs: 120_000, pollMs: 25 }) {
+        this.dir = dir;
+        this.opts = opts;
+    }
+    /** The lock file for a key (`<chain_id> <genesis_hash> <address>`). */
+    file(key) {
+        return join(this.dir, `agent-nonce-${keyHash(key)}.lock`);
+    }
+    /** Runs `f` holding `key`'s lock: no other call in this process, or other process sharing the directory, holds it meanwhile. */
+    async run(key, f) {
+        const before = this.queues.get(key) ?? Promise.resolve();
+        let done;
+        const mine = new Promise((r) => (done = r));
+        const tail = before.then(() => mine);
+        this.queues.set(key, tail);
+        await before;
+        try {
+            return await this.holdingFile(key, f);
+        }
+        finally {
+            done();
+            if (this.queues.get(key) === tail)
+                this.queues.delete(key);
+        }
+    }
+    async holdingFile(key, f) {
+        const lock = this.file(key);
+        mkdirSync(dirname(lock), { recursive: true });
+        const token = `${process.pid} ${Date.now()} ${Math.random().toString(36).slice(2)}`;
+        const start = Date.now();
+        for (;;) {
+            try {
+                const fd = openSync(lock, "wx", 0o600);
+                try {
+                    writeFileSync(fd, token);
+                }
+                finally {
+                    closeSync(fd);
+                }
+                break;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+            }
+            // Held: by a process that's gone, or one that hasn't touched its lock for too long, it's taken over.
+            try {
+                const seen = readFileSync(lock, "utf8");
+                const holder = Number(seen.split(" ")[0]);
+                const stale = Date.now() - statSync(lock).mtimeMs > this.opts.staleMs;
+                if (stale || (Number.isSafeInteger(holder) && holder > 0 && holder !== process.pid && !alive(holder)))
+                    this.takeOver(lock, seen);
+            }
+            catch {
+                /* it went away, or is being written: try again */
+            }
+            if (Date.now() - start > this.opts.waitMs)
+                throw new Error(`another Blockula MCP has been sending from this account for over ${Math.round(this.opts.waitMs / 1000)} s (${lock}); if none is running, delete that file`);
+            await sleep(this.opts.pollMs);
+        }
+        // While `f` runs, a live holder keeps its lock fresh: a call that takes longer than `staleMs`
+        // (a node that hangs until BLOCKULA_TIMEOUT_MS) isn't a stuck holder.
+        const beat = setInterval(() => {
+            try {
+                if (readFileSync(lock, "utf8") !== token)
+                    return; // taken over: it's not ours to touch
+                const now = new Date();
+                utimesSync(lock, now, now);
+            }
+            catch {
+                /* gone */
+            }
+        }, this.opts.refreshMs ?? Math.max(1, Math.floor(this.opts.staleMs / 4)));
+        beat.unref();
+        try {
+            return await f();
+        }
+        finally {
+            clearInterval(beat);
+            try {
+                if (readFileSync(lock, "utf8") === token)
+                    rmSync(lock, { force: true });
+            }
+            catch {
+                /* taken over as stale, or removed */
+            }
+        }
+    }
+    /**
+     * Removes `lock`, which was read as `seen` and judged dead or stuck. Several waiters can judge
+     * the same lock at once, and the first one's takeover lets another process create a fresh lock
+     * before the second one's removal: deleting by name would then delete that fresh lock, and two
+     * holders would work on one account. So the lock is renamed to a name of this takeover's own
+     * (only one rename of it succeeds, and a lock that's gone throws ENOENT: nothing to do), and
+     * deleted only if what was moved is `seen`. If it's another lock, it's put back, unless a third
+     * process has already made a new one (then nothing can undo that; the window is the few calls
+     * between the rename and the link).
+     */
+    takeOver(lock, seen) {
+        const grave = `${lock}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2)}.stale`;
+        renameSync(lock, grave);
+        try {
+            if (readFileSync(grave, "utf8") !== seen)
+                linkSync(grave, lock);
+        }
+        catch {
+            /* a new lock is there already, or the moved one is unreadable: it's dropped with the grave */
+        }
+        finally {
+            rmSync(grave, { force: true });
+        }
+    }
+}
+const keyHash = (key) => createHash("sha256").update(key).digest("hex").slice(0, 24);
+/**
+ * One small file per (chain, account), beside its lock: every write to it happens while holding
+ * that account's AccountLocks lock, so two processes never write it at once.
+ *
+ * A node's next_nonce can lag what this MCP knows: its mempool may not show a tx another node
+ * took, and right after a block runs its account read can still be the one before (observed on a
+ * dev chain: "bad nonce: expected 5, got 4" for the tx after a finalized one). Nonces only go up,
+ * so a tx that ran keeps its nonce spent for good, and a pending one holds its nonce until its
+ * valid_until. One that was dropped or refused holds nothing: its nonce may be free again.
+ */
+export class NonceTracker {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    file(key) {
+        return join(this.dir, `agent-nonce-${keyHash(key)}.json`);
+    }
+    read(key) {
+        try {
+            const n = JSON.parse(readFileSync(this.file(key), "utf8"));
+            if (!n || n.key !== key)
+                return { key };
+            const ran = Number.isSafeInteger(n.ran) && n.ran >= 0 ? n.ran : undefined;
+            const p = n.pending;
+            const pending = p && Number.isSafeInteger(p.nonce) && p.nonce >= 0 && Number.isSafeInteger(p.valid_until) ? { nonce: p.nonce, valid_until: p.valid_until } : undefined;
+            return { key, ...(ran !== undefined ? { ran } : {}), ...(pending ? { pending } : {}) };
+        }
+        catch {
+            return { key };
+        }
+    }
+    write(n) {
+        try {
+            mkdirSync(this.dir, { recursive: true });
+            const tmp = `${this.file(n.key)}.${process.pid}.tmp`;
+            writeFileSync(tmp, JSON.stringify(n), { mode: 0o600 });
+            renameSync(tmp, this.file(n.key));
+        }
+        catch {
+            /* informational only */
+        }
+    }
+    /** The lowest nonce the next tx may take: past the last one that ran, and past a pending one while it can still run (the chain at or before its valid_until). */
+    floor(key, height) {
+        const n = this.read(key);
+        const after = [n.ran !== undefined ? n.ran + 1 : undefined, n.pending && height <= n.pending.valid_until ? n.pending.nonce + 1 : undefined].filter((x) => x !== undefined);
+        return after.length ? Math.max(...after) : undefined;
+    }
+    /** A tx was submitted and isn't final yet. Call holding the account's lock. */
+    pending(key, nonce, validUntil) {
+        const n = this.read(key);
+        this.write({ ...n, pending: { nonce, valid_until: validUntil } });
+    }
+    /** The tx with this nonce ran in a block (finalized, or failed: its fee was charged). Call holding the account's lock. */
+    ran(key, nonce) {
+        const n = this.read(key);
+        const pending = n.pending && n.pending.nonce > nonce ? n.pending : undefined;
+        this.write({ key, ran: Math.max(n.ran ?? -1, nonce), ...(pending ? { pending } : {}) });
+    }
+    /**
+     * Forgets what's known: after the node refused a tx for a nonce past its own, so a wrong record
+     * (a node that said a tx ran when it didn't) can't block every later tx. Call holding the lock.
+     */
+    forget(key) {
+        rmSync(this.file(key), { force: true });
+    }
+    /** The tx with this nonce was dropped or refused: it holds its nonce no longer. Call holding the account's lock. */
+    settled(key, nonce) {
+        const n = this.read(key);
+        if (n.pending?.nonce !== nonce)
+            return;
+        this.write({ key, ...(n.ran !== undefined ? { ran: n.ran } : {}) });
+    }
+}

package/dist/network.d.ts

@@ -1,4 +1,10 @@
-export type NetworkKey = "mainnet" | "testnet" | "local" | "custom";
+export type NetworkKey = "testnet" | "local" | "custom";
+/**
+ * The chain id Blockula's mainnet was to have: no chain runs under it, so nothing is used under it
+ * by accident (`unpinnedBlockula1`), and where an address is needed an unproven name isn't signed
+ * on it (index.ts `onBlockula1`).
+ */
+export declare const BLOCKULA_1 = "blockula-1";
 /** What the node must report in `/api/status`. */
 export interface Pin {
     chainId?: string;
@@ -10,24 +16,30 @@ export interface Network {
     label: string;
     rpc: string;
     pin: Pin;
-    /** Real money: the copy and the defaults get stricter. */
-    mainnet: boolean;
     /** Remember the first chain this node reports (TOFU) across restarts. Off for local dev chains, which `--reset` replaces. */
     remember: boolean;
     /**
      * Independent nodes of the same chain (BLOCKULA_WITNESSES, comma-separated): names that end up
      * in a signature are proven against them (audit gap-7-1). Empty: a name is the node's word.
+     * Unset, and the node isn't one of its network's public RPCs (your own node), they're those
+     * RPCs (`defaultWitnesses`; OPERATOR-6).
      */
     witnesses: string[];
+    /** BLOCKULA_WITNESSES was set (`none` included): no witnesses are added by default. */
+    witnessesSet: boolean;
 }
 export declare const LOCAL_RPC = "http://localhost:7070";
 export declare const TESTNET_RPC = "https://blockula-testnet.fly.dev";
-/** Public mainnet RPC endpoints, run by independent operators. Empty until launch: set BLOCKULA_RPC. */
+/**
+ * Nothing reads this: the MCP has no mainnet network. It stays because
+ * `scripts/pin-network.sh --mainnet --rpc` writes it and `scripts/test-pin-network.sh` checks
+ * that; it goes when that mode does.
+ */
 export declare const MAINNET_RPCS: string[];
 /**
  * Chains whose genesis is known: any node claiming one of these chain ids must report this
- * genesis hash, whatever network it was configured as. `blockula-1`'s hash is added here once the
- * genesis ceremony has produced it (docs/GENESIS_CEREMONY.md).
+ * genesis hash, whatever network it was configured as. A release adds a chain's here
+ * (scripts/pin-network.sh).
  */
 export declare const KNOWN_GENESIS: Record<string, string>;
 /**
@@ -49,11 +61,53 @@ export interface GenesisClock {
  */
 export declare function clockFrom(genesis: unknown, chainId: string): GenesisClock | undefined;
 /** The networks the MCP knows by name. */
-export declare const KNOWN_NETWORKS: Record<Exclude<NetworkKey, "custom">, Omit<Network, "rpc" | "witnesses"> & {
+export declare const KNOWN_NETWORKS: Record<Exclude<NetworkKey, "custom">, Omit<Network, "rpc" | "witnesses" | "witnessesSet"> & {
     rpc?: string;
 }>;
-/** A node URL: http(s) without credentials; plain http only on this machine or a private network. */
+/**
+ * The witnesses a node of `chainId` gets when BLOCKULA_WITNESSES is unset: the chain's public RPCs,
+ * unless the node is one of them. So your own node's answers about names and heights are checked
+ * against the public ones (OPERATOR-6). None for chains without public RPCs (dev chains, and the
+ * chains people launch themselves: there, BLOCKULA_WITNESSES lists other nodes).
+ */
+export declare function defaultWitnesses(chainId: string | undefined, rpc: string): string[];
+/**
+ * What `status` calls the network: once the node's chain is known, a node on this machine that
+ * is on a public network is "your node on <it>", never a "local dev node".
+ */
+export declare function networkLabel(net: Network, chainId?: string): string;
+/**
+ * A node URL in one spelling: the scheme and host lowercased, a default port and dot segments
+ * dropped (the URL parser's own normalization), no trailing dot on the host and no trailing
+ * slash. So a node compares equal however it's written: `https://Blockula-Testnet.fly.dev:443/.`
+ * is the public RPC, and is never its own witness (audit MCK-1). What isn't an http(s) URL comes
+ * back as it is.
+ */
+export declare function canonicalUrl(u: string): string;
+/**
+ * A node URL, spelled canonically (canonicalUrl): http(s) without credentials, a query or a
+ * fragment (the client appends /api/… to it); plain http only on this machine or a private network.
+ */
 export declare function checkRpcUrl(u: string, what?: string): string;
+/**
+ * The chain ids this MCP pins, and keys its ledger (spend.ts `chainKey`), lock and nonce records
+ * and grant files by: 1 to 64 letters, digits, '-', '_' and '.'. A genesis built for a public
+ * network has letters, digits and '-' (node/src/genesis_builder.rs, at most 64: MAX_CHAIN_ID), so
+ * every real chain fits. A node reporting anything else (a path separator, a space) is refused
+ * when its chain is pinned (`unusableChain`), so nothing it names is ever used as a file name or
+ * a ledger key (audit MCK-3).
+ */
+export declare const CHAIN_ID: RegExp;
+/**
+ * Why a node's chain can't be pinned at all, or null: a chain id outside CHAIN_ID, or a genesis
+ * hash that isn't 64 hex characters, can't key what this MCP keeps per chain. (A node that reports
+ * no genesis hash is pinned by its chain id alone, as before; it can't sign, and `use_account`
+ * says that's why.)
+ */
+export declare function unusableChain(status: {
+    chain_id?: unknown;
+    genesis_hash?: unknown;
+}): string | null;
 /** `--network <name>` or `--network=<name>` from the command line. */
 export declare function networkArg(argv: string[]): string | undefined;
 /**
@@ -68,6 +122,15 @@ export declare function mismatch(pin: Pin, status: {
     genesis_hash?: unknown;
     address_prefix?: unknown;
 }): string | null;
+/**
+ * Why a node that says it's on blockula-1 is refused, or null: the pin (configured, or remembered
+ * from a configuration that named it) isn't that chain. A node that reports blockula-1 is never
+ * trusted on first use, as the CLI doesn't (`cli_net`): set BLOCKULA_CHAIN_ID=blockula-1 to mean it.
+ * (A pin on another chain is refused by `mismatch` first, in its own words.)
+ */
+export declare function unpinnedBlockula1(pin: Pin, status: {
+    chain_id?: unknown;
+}): string | null;
 /** The pin after a first status: every field the node reported that wasn't pinned yet. */
 export declare function completePin(pin: Pin, status: {
     chain_id?: unknown;
@@ -87,6 +150,7 @@ export declare class KnownChains {
     /** The genesis clock remembered for this chain (`clockFrom` of the first `/api/genesis` read for it). */
     clock(net: Network, chainId: string, genesisHash: string): GenesisClock | undefined;
     saveClock(net: Network, chainId: string, genesisHash: string, clock: GenesisClock): void;
+    /** Sets one entry (and drops the entries `drop` names, in the same write). */
     private write;
 }
 /**
@@ -97,5 +161,9 @@ export declare class KnownChains {
  * pinned on first use instead of refused for the old one's genesis.
  */
 export declare function effectivePin(net: Network, remembered?: Pin): Pin;
-/** The error an agent sees when a node is on the wrong chain: what happened and what the user can do. */
-export declare function mismatchError(net: Network, why: string, knownChainsFile: string): Error;
+/**
+ * The error an agent sees when a node is on the wrong chain: what happened and what the user can
+ * do. `relaunched` is false for a node whose chain can't be pinned at all (`unusableChain`):
+ * forgetting what was remembered wouldn't help there.
+ */
+export declare function mismatchError(net: Network, why: string, knownChainsFile: string, relaunched?: boolean): Error;