@aibtc/mcp-server 1.65.0 → 1.66.0

package/dist/services/legion.service.js

@@ -0,0 +1,410 @@
+/**
+ * AIBTC News Legion (news-gov-v5) chain reads.
+ *
+ * Everything here reads the deployed contracts rather than trusting constants:
+ * governance parameters, the timing mode (which clock the windows count on),
+ * and the sBTC token the treasury actually holds all come off chain and are
+ * cached per process. A doc that drifts from the contract is a doc; a read that
+ * drifts from the contract is a bug, so there is nothing to drift.
+ */
+import { ClarityType, cvToJSON, deserializeCV, getAddressFromPrivateKey, principalCV, uintCV, } from "@stacks/transactions";
+import { LEGION_GOV_CONTRACT, LEGION_NETWORK, LEGION_TREASURY_CONTRACT, ORDINALS_CONTENT_BASE, ORDINALS_INSCRIPTION_BASE, } from "../config/legion.js";
+import { getHiroApi } from "./hiro-api.js";
+import { getAccount } from "./x402.service.js";
+// ---------------------------------------------------------------------------
+// Clarity value → plain JS
+// ---------------------------------------------------------------------------
+/**
+ * Deep-unwrap a ClarityValue into plain JS. `cvToValue` only unwraps the top
+ * level — nested tuples and optionals come back as `{type, value}` envelopes —
+ * so the legion's tuple-heavy views need this instead.
+ *
+ * uints/ints become strings to stay exact; callers narrow with `num()`.
+ */
+export function simplifyCV(cv) {
+    switch (cv.type) {
+        case ClarityType.BoolTrue:
+            return true;
+        case ClarityType.BoolFalse:
+            return false;
+        case ClarityType.Int:
+        case ClarityType.UInt:
+            return cv.value.toString();
+        case ClarityType.Buffer:
+            return `0x${cv.value}`;
+        case ClarityType.StringASCII:
+        case ClarityType.StringUTF8:
+        case ClarityType.PrincipalStandard:
+        case ClarityType.PrincipalContract:
+            return cv.value;
+        case ClarityType.OptionalNone:
+            return null;
+        case ClarityType.OptionalSome:
+        case ClarityType.ResponseOk:
+        case ClarityType.ResponseErr:
+            return simplifyCV(cv.value);
+        case ClarityType.List:
+            return cv.value.map(simplifyCV);
+        case ClarityType.Tuple: {
+            const out = {};
+            for (const [key, value] of Object.entries(cv.value)) {
+                out[key] = simplifyCV(value);
+            }
+            return out;
+        }
+        default:
+            return cvToJSON(cv).value;
+    }
+}
+/** A uint field from a simplified tuple, as a JS number. */
+export function num(value) {
+    return Number(value);
+}
+// ---------------------------------------------------------------------------
+// Contract reads
+// ---------------------------------------------------------------------------
+/**
+ * Call a read-only function on a legion contract and return it deep-unwrapped.
+ * Always reads the legion's own chain, never the globally configured one.
+ */
+export async function readLegionContract(contractId, functionName, functionArgs = []) {
+    const hiro = getHiroApi(LEGION_NETWORK);
+    const sender = contractId.split(".")[0];
+    const result = await hiro.callReadOnlyFunction(contractId, functionName, functionArgs, sender);
+    if (!result.okay || !result.result) {
+        throw new Error(`${contractId}::${functionName} failed: ${result.cause ?? "no result"}`);
+    }
+    const hex = result.result.startsWith("0x")
+        ? result.result.slice(2)
+        : result.result;
+    return simplifyCV(deserializeCV(Buffer.from(hex, "hex")));
+}
+export function readGov(functionName, functionArgs = []) {
+    return readLegionContract(LEGION_GOV_CONTRACT, functionName, functionArgs);
+}
+export function readTreasury(functionName, functionArgs = []) {
+    return readLegionContract(LEGION_TREASURY_CONTRACT, functionName, functionArgs);
+}
+let paramsCache = null;
+let timingModeCache = null;
+let tokenCache = null;
+/** Every governance parameter, straight from `get-params`. */
+export async function getParams() {
+    if (paramsCache)
+        return paramsCache;
+    const raw = (await readGov("get-params"));
+    paramsCache = {
+        votingQuorum: num(raw.votingQuorum),
+        votingThreshold: num(raw.votingThreshold),
+        vetoQuorum: num(raw.vetoQuorum),
+        minParticipants: num(raw.minParticipants),
+        minWeight: num(raw.minWeight),
+        minContribution: num(raw.minContribution),
+        drawBps: num(raw.drawBps),
+        votingDelay: num(raw.votingDelay),
+        voteWindow: num(raw.voteWindow),
+        vetoWindow: num(raw.vetoWindow),
+        concludeWindow: num(raw.concludeWindow),
+        proposeInterval: num(raw.proposeInterval),
+    };
+    return paramsCache;
+}
+/**
+ * Which clock the windows count on. `"TEST-STACKS-BLOCKS"` counts Stacks
+ * blocks; `"PROD-BURN"` counts Bitcoin burn blocks. Never assume — a window
+ * measured against the wrong tip is off by a factor of ten.
+ */
+export async function getTimingMode() {
+    if (timingModeCache)
+        return timingModeCache;
+    timingModeCache = (await readGov("get-timing-mode"));
+    return timingModeCache;
+}
+/**
+ * The sBTC token the treasury actually moves, plus its fungible-token asset
+ * name — both needed to write an exact post-condition. Read from the treasury
+ * and its contract interface so a post-condition can never name the wrong asset.
+ */
+export async function getLegionToken() {
+    if (tokenCache)
+        return tokenCache;
+    const contract = (await readTreasury("get-token"));
+    const iface = await getHiroApi(LEGION_NETWORK).getContractInterface(contract);
+    const assetName = iface.fungible_tokens?.[0]?.name;
+    if (!assetName) {
+        throw new Error(`${contract} declares no fungible token — cannot build a post-condition for it.`);
+    }
+    tokenCache = { contract, assetName };
+    return tokenCache;
+}
+/**
+ * The height the contract's windows are measured against, on the clock
+ * `get-timing-mode` names.
+ */
+export async function getClockHeight() {
+    const [timingMode, info] = await Promise.all([
+        getTimingMode(),
+        getHiroApi(LEGION_NETWORK).getCoreApiInfo(),
+    ]);
+    const clock = timingMode === "PROD-BURN" ? "burn" : "stacks";
+    return {
+        height: clock === "burn" ? info.burn_block_height : info.stacks_tip_height,
+        clock,
+        timingMode,
+    };
+}
+// ---------------------------------------------------------------------------
+// The signing account, pinned to the legion's chain
+// ---------------------------------------------------------------------------
+/**
+ * The unlocked wallet, re-derived for the legion's network.
+ *
+ * The same private key yields a different address per chain, so a mainnet
+ * session still signs legion calls from its testnet address against the testnet
+ * node. This is the guard that makes a mainnet-configured server safe here.
+ */
+export async function getLegionAccount() {
+    const base = await getAccount();
+    if (base.network === LEGION_NETWORK)
+        return base;
+    return {
+        ...base,
+        address: getAddressFromPrivateKey(base.privateKey, LEGION_NETWORK),
+        network: LEGION_NETWORK,
+    };
+}
+export async function getStory(proposalId) {
+    const raw = (await readGov("get-story", [uintCV(proposalId)]));
+    if (!raw)
+        return null;
+    return {
+        proposer: String(raw.proposer),
+        bond: num(raw.bond),
+        draw: num(raw.draw),
+        createdAt: num(raw.createdAt),
+        voteEnd: num(raw.voteEnd),
+        eligibleSnapshot: num(raw.eligibleSnapshot),
+        yesWeight: num(raw.yesWeight),
+        noWeight: num(raw.noWeight),
+        vetoWeight: num(raw.vetoWeight),
+        voterCount: num(raw.voterCount),
+        status: num(raw.status),
+        reason: String(raw.reason ?? ""),
+    };
+}
+export async function getStoryMeta(proposalId) {
+    const raw = (await readGov("get-story-meta", [uintCV(proposalId)]));
+    if (!raw)
+        return null;
+    return {
+        title: String(raw.title ?? ""),
+        description: String(raw.description ?? ""),
+        link: String(raw.link ?? ""),
+    };
+}
+/**
+ * `"none" | "pending" | "voting" | "veto" | "concludable" | "expired" |
+ * "passed" | "failed"` — the contract's own view of where a piece stands.
+ */
+export async function getPhase(proposalId) {
+    return (await readGov("get-phase", [uintCV(proposalId)]));
+}
+export async function getLastProposalId() {
+    return num(await readGov("get-last-proposal-id"));
+}
+export async function getVoteRecord(proposalId, voter) {
+    const raw = (await readGov("get-vote-record", [
+        uintCV(proposalId),
+        principalCV(voter),
+    ]));
+    if (!raw)
+        return null;
+    return { support: Boolean(raw.support), weight: num(raw.weight) };
+}
+export async function getVetoRecord(proposalId, voter) {
+    const raw = (await readGov("get-veto-record", [
+        uintCV(proposalId),
+        principalCV(voter),
+    ]));
+    if (!raw)
+        return null;
+    return { weight: num(raw.weight) };
+}
+/** Every propose precondition folded into one read, with the individual gates. */
+export async function getProposeStatus(who) {
+    const raw = (await readGov("propose-status", [principalCV(who)]));
+    return {
+        canPropose: Boolean(raw.canPropose),
+        eligible: Boolean(raw.eligible),
+        slotOpen: Boolean(raw.slotOpen),
+        noLiveProposal: Boolean(raw.noLiveProposal),
+        poolOk: Boolean(raw.poolOk),
+        nextProposeHeight: num(raw.nextProposeHeight),
+        lockOnPropose: num(raw.lockOnPropose),
+        draw: num(raw.draw),
+        freeWeight: num(raw.freeWeight),
+    };
+}
+/** Why a propose would revert right now, in the caller's words. */
+export function proposeBlockers(status, minWeight) {
+    const blockers = [];
+    if (!status.eligible) {
+        blockers.push(`your weight is below minWeight (${minWeight}) — call legion_contribute first`);
+    }
+    if (!status.noLiveProposal) {
+        blockers.push("you already have a live proposal — one per principal until it concludes or lapses");
+    }
+    if (!status.slotOpen) {
+        blockers.push(`the contract-wide propose interval has not elapsed — next open at height ${status.nextProposeHeight}`);
+    }
+    if (!status.poolOk) {
+        blockers.push("the pool is empty or the draw would round to zero sats");
+    }
+    return blockers;
+}
+/** When each window opens and closes, on the clock the contract counts. */
+export function buildTimeline(story, params, height, clock) {
+    const votingOpensAt = story.createdAt + params.votingDelay;
+    const vetoEnd = story.voteEnd + params.vetoWindow;
+    const concludeDeadline = vetoEnd + params.concludeWindow;
+    const nextBoundary = [votingOpensAt, story.voteEnd, vetoEnd, concludeDeadline].find((boundary) => boundary > height);
+    return {
+        createdAt: story.createdAt,
+        votingOpensAt,
+        voteEnd: story.voteEnd,
+        vetoEnd,
+        concludeDeadline,
+        currentHeight: height,
+        clock,
+        blocksUntilNextTransition: nextBoundary === undefined ? null : nextBoundary - height,
+    };
+}
+/**
+ * What `conclude` would decide if it ran at this height, following the
+ * contract's decision order exactly (integer division included, since Clarity
+ * floors every percentage).
+ *
+ * A story that is already terminal reports what the contract RECORDED, not a
+ * forecast. Forecasting a settled piece would be worse than useless: a passed
+ * proposal is necessarily past its conclude window, so the forecast branch
+ * would call every settled piece "expired".
+ */
+export function predictOutcome(story, params, poolBalance, height) {
+    const cast = story.yesWeight + story.noWeight;
+    const eligible = story.eligibleSnapshot;
+    const quorumPct = eligible > 0 ? Math.floor((cast * 100) / eligible) : 0;
+    const yesPct = cast > 0 ? Math.floor((story.yesWeight * 100) / cast) : 0;
+    const vetoPct = eligible > 0 ? Math.floor((story.vetoWeight * 100) / eligible) : 0;
+    const participantsMet = story.voterCount >= params.minParticipants;
+    const quorumMet = eligible > 0 && participantsMet && quorumPct >= params.votingQuorum;
+    const thresholdMet = cast > 0 && yesPct >= params.votingThreshold;
+    const vetoed = eligible > 0 && vetoPct >= params.vetoQuorum;
+    const base = {
+        cast,
+        quorumPct,
+        yesPct,
+        vetoPct,
+        quorumMet,
+        thresholdMet,
+        vetoed,
+        participantsMet,
+    };
+    // Already terminal: report the record.
+    if (story.status !== 0) {
+        const settledOutcome = story.status === 1 ? "passed" : story.status === 3 ? "expired" : "failed";
+        return {
+            ...base,
+            settled: true,
+            outcome: settledOutcome,
+            reason: story.reason || settledOutcome,
+            payout: story.status === 1 ? story.draw : 0,
+        };
+    }
+    const concludeDeadline = story.voteEnd + params.vetoWindow + params.concludeWindow;
+    if (height >= concludeDeadline) {
+        return {
+            ...base,
+            settled: false,
+            outcome: "expired",
+            reason: "not-concluded — the conclude window closed with nobody calling it",
+            payout: 0,
+        };
+    }
+    if (vetoed) {
+        return { ...base, settled: false, outcome: "failed", reason: "vetoed", payout: 0 };
+    }
+    if (!quorumMet) {
+        return { ...base, settled: false, outcome: "failed", reason: "no-quorum", payout: 0 };
+    }
+    if (!thresholdMet) {
+        return { ...base, settled: false, outcome: "failed", reason: "voted-down", payout: 0 };
+    }
+    if (story.draw > poolBalance) {
+        return { ...base, settled: false, outcome: "failed", reason: "pool-short", payout: 0 };
+    }
+    return { ...base, settled: false, outcome: "passed", reason: "paid", payout: story.draw };
+}
+// ---------------------------------------------------------------------------
+// Links and validation
+// ---------------------------------------------------------------------------
+/**
+ * Accept either a bare inscription id (`<txid>i0`) or a full URL, and return
+ * the link the contract should store.
+ *
+ * A bare id becomes the VIEWER url, not the content url: that is what every
+ * proposal already on chain uses, and it is what a voter wants from a click.
+ * The reader at legions.aibtc.news accepts either form and both bare ids.
+ */
+export function normalizeOrdinalsLink(input) {
+    const trimmed = input.trim();
+    if (/^[0-9a-f]{64}i\d+$/i.test(trimmed)) {
+        return `${ORDINALS_INSCRIPTION_BASE}${trimmed.toLowerCase()}`;
+    }
+    if (/^https?:\/\//i.test(trimmed))
+        return trimmed;
+    throw new Error(`"${input}" is neither an inscription id (<64-hex-txid>i0) nor a URL. ` +
+        `Pass the inscription id from legion_inscribe_reveal, or a full https:// link.`);
+}
+/** The inscription id inside an ordinals link, when there is one. */
+export function inscriptionIdFromLink(link) {
+    const match = link.match(/([0-9a-f]{64}i\d+)/i);
+    return match ? match[1].toLowerCase() : null;
+}
+/**
+ * The raw-bytes url for a stored link, so a voter can read the piece rather
+ * than just look at where it lives. Null when the link names no inscription.
+ */
+export function contentUrlFromLink(link) {
+    const id = inscriptionIdFromLink(link);
+    return id ? `${ORDINALS_CONTENT_BASE}${id}` : null;
+}
+/**
+ * Clarity `string-ascii` holds one byte per character, so a smart quote or an
+ * em dash pasted into a headline is a revert, not a truncation. Catch it here
+ * with a message that names the character.
+ */
+export function assertAscii(value, field, maxLength) {
+    const offender = [...value].find((char) => char.charCodeAt(0) > 127);
+    if (offender) {
+        throw new Error(`${field} must be ASCII — "${offender}" (U+${offender
+            .charCodeAt(0)
+            .toString(16)
+            .toUpperCase()
+            .padStart(4, "0")}) is not. Clarity string-ascii cannot hold it.`);
+    }
+    if (value.length > maxLength) {
+        throw new Error(`${field} is ${value.length} characters; the contract accepts at most ${maxLength}.`);
+    }
+}
+/** `(err uXXX)` from a failed read or a broadcast rejection, as a sentence. */
+export function explainError(error, errors) {
+    const text = error instanceof Error ? error.message : String(error);
+    const match = text.match(/\bu(\d{3})\b/);
+    if (match) {
+        const explanation = errors[Number(match[1])];
+        if (explanation)
+            return `${text} — ${explanation}`;
+    }
+    return text;
+}
+//# sourceMappingURL=legion.service.js.map

package/dist/services/x402.service.d.ts

@@ -9,6 +9,28 @@ export declare class X402RateLimitError extends Error {
     readonly retryAfterSeconds: number;
     constructor(message: string, retryAfterSeconds: number);
 }
+/**
+ * How long a completed x402 request suppresses an identical repeat.
+ *
+ * This was 60s, which is shorter than a realistic agent retry: an agent that
+ * reports a failure to its operator and retries takes minutes, not seconds.
+ * In the incident behind #630 the two payments landed 362s apart — 6x the old
+ * window — so the guard never engaged and the endpoint was paid twice.
+ *
+ * The asymmetry favours a long window: a false dedup hit costs a wait (and
+ * still returns the prior txid so the caller can verify), while a miss costs a
+ * duplicate on-chain payment that cannot be reversed. Deliberate repeat
+ * purchases of the same endpoint with the same params must wait it out or vary
+ * a param; raise or lower via X402_DEDUP_TTL_SECONDS.
+ */
+export declare const X402_DEDUP_TTL_MS: number;
+/**
+ * Point the dedup cache at a different state file and drop what is in memory.
+ *
+ * Also the seam tests use to simulate a restart: re-pointing at the same file
+ * clears memory and forces the next read to come off disk.
+ */
+export declare function setDedupStateFile(file: string): void;
 /**
  * Convert mnemonic to account
  */
@@ -168,14 +190,21 @@ export declare function probeEndpoint(options: {
  */
 export declare function generateDedupKey(method: string, url: string, params?: Record<string, string>, data?: Record<string, unknown>): string;
 /**
- * Check if a request was recently processed (within 60s)
+ * Check if a request was recently processed (within X402_DEDUP_TTL_MS).
+ *
+ * Loads persisted entries first so a payment broadcast before a server restart
+ * still suppresses the retry that follows it.
+ *
  * @returns txid if duplicate found, null otherwise
  */
-export declare function checkDedupCache(key: string): string | null;
+export declare function checkDedupCache(key: string): Promise<string | null>;
 /**
- * Record a transaction in the dedup cache
+ * Record a transaction in the dedup cache and persist it.
+ *
+ * Awaits the write so the entry survives a crash immediately after a payment —
+ * the window where losing it costs a duplicate payment.
  */
-export declare function recordTransaction(key: string, txid: string): void;
+export declare function recordTransaction(key: string, txid: string): Promise<void>;
 /**
  * Check if account has sufficient balance to pay for x402 endpoint.
  * @throws InsufficientBalanceError if balance is too low

package/dist/services/x402.service.js

@@ -10,6 +10,9 @@ import { formatStx, formatSbtc } from "../utils/formatting.js";
 import { getSbtcService } from "./sbtc.service.js";
 import { getHiroApi } from "./hiro-api.js";
 import { createHash } from "crypto";
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
 import { InsufficientBalanceError } from "../utils/errors.js";
 import { getContracts, parseContractId } from "../config/contracts.js";
 import { resolveDefaultFee } from "../utils/fee.js";
@@ -104,13 +107,167 @@ export class X402RateLimitError extends Error {
         this.name = "X402RateLimitError";
     }
 }
+/**
+ * How long a completed x402 request suppresses an identical repeat.
+ *
+ * This was 60s, which is shorter than a realistic agent retry: an agent that
+ * reports a failure to its operator and retries takes minutes, not seconds.
+ * In the incident behind #630 the two payments landed 362s apart — 6x the old
+ * window — so the guard never engaged and the endpoint was paid twice.
+ *
+ * The asymmetry favours a long window: a false dedup hit costs a wait (and
+ * still returns the prior txid so the caller can verify), while a miss costs a
+ * duplicate on-chain payment that cannot be reversed. Deliberate repeat
+ * purchases of the same endpoint with the same params must wait it out or vary
+ * a param; raise or lower via X402_DEDUP_TTL_SECONDS.
+ */
+export const X402_DEDUP_TTL_MS = parseSatsCap("X402_DEDUP_TTL_SECONDS", 900) * 1000; // 15 minutes
 // Transaction deduplication cache: {dedupKey -> {txid, timestamp}}
 const dedupCache = new Map();
+/**
+ * Where the dedup cache is persisted.
+ *
+ * Memory alone left the guard open to the same double-pay it exists to stop: an
+ * MCP server restarts routinely (client reconnect, config change, crash), and a
+ * restart inside the TTL window dropped every entry. An agent retrying after one
+ * sailed past the guard and paid a second time — #630's outcome reached by a
+ * different route.
+ *
+ * Keys are SHA-256 digests (see generateDedupKey) and values are chain txids, so
+ * no request content reaches disk. The file is still written 0600 under a 0700
+ * directory to match the wallet store.
+ *
+ * Caveat: entries are keyed by request, not by payer. Switching wallets and
+ * repeating a request inside the window reports a hit for the other wallet's
+ * payment. That is the asymmetry the TTL already takes — a false hit costs a
+ * wait and still surfaces the prior txid to verify, while a miss costs an
+ * irreversible duplicate payment.
+ *
+ * Override the location with X402_DEDUP_STATE_FILE.
+ */
+let dedupStateFile = process.env.X402_DEDUP_STATE_FILE ||
+    path.join(os.homedir(), ".aibtc", "x402-dedup.json");
+let dedupLoad = null;
+let dedupWriteLock = Promise.resolve();
+/**
+ * Point the dedup cache at a different state file and drop what is in memory.
+ *
+ * Also the seam tests use to simulate a restart: re-pointing at the same file
+ * clears memory and forces the next read to come off disk.
+ */
+export function setDedupStateFile(file) {
+    dedupStateFile = file;
+    dedupLoad = null;
+    dedupCache.clear();
+}
+function isFresh(entry, now) {
+    return now - entry.timestamp <= X402_DEDUP_TTL_MS;
+}
+/** Read persisted entries. A missing file is the normal first-run case. */
+async function readDedupState() {
+    let raw;
+    try {
+        raw = await fs.readFile(dedupStateFile, "utf8");
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            console.error(`[x402-dedup] Could not read ${dedupStateFile}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object")
+            return {};
+        return parsed;
+    }
+    catch {
+        // A corrupt file must not brick every x402 call. Report it and continue
+        // with the in-memory guard; the next write replaces the file.
+        console.error(`[x402-dedup] Ignoring corrupt state at ${dedupStateFile}`);
+        return {};
+    }
+}
+/**
+ * Load persisted entries into memory once per state file.
+ *
+ * Must be awaited before any dedup read: answering from a not-yet-loaded cache
+ * would report "no prior payment" for one that is sitting on disk, which is the
+ * exact miss this persistence closes.
+ */
+async function ensureDedupLoaded() {
+    if (!dedupLoad) {
+        dedupLoad = (async () => {
+            const persisted = await readDedupState();
+            const now = Date.now();
+            for (const [key, entry] of Object.entries(persisted)) {
+                if (!entry ||
+                    typeof entry.txid !== "string" ||
+                    typeof entry.timestamp !== "number") {
+                    continue;
+                }
+                if (!isFresh(entry, now))
+                    continue;
+                // Anything recorded in this process is at least as fresh as disk.
+                const existing = dedupCache.get(key);
+                if (!existing || existing.timestamp < entry.timestamp) {
+                    dedupCache.set(key, entry);
+                }
+            }
+        })();
+    }
+    return dedupLoad;
+}
+/**
+ * Merge memory over disk and write atomically, dropping expired entries.
+ *
+ * Re-reads inside the lock so a second server instance sharing the file does not
+ * lose the entries this one never saw. A failure here is logged rather than
+ * thrown: the caller records *after* funds have already moved, so rejecting
+ * would turn a recorded payment into a reported error while leaving the
+ * in-memory guard intact.
+ */
+async function persistDedupCache() {
+    dedupWriteLock = dedupWriteLock
+        .then(async () => {
+        const onDisk = await readDedupState();
+        const now = Date.now();
+        const merged = {};
+        for (const [key, entry] of Object.entries(onDisk)) {
+            if (entry &&
+                typeof entry.txid === "string" &&
+                typeof entry.timestamp === "number" &&
+                isFresh(entry, now)) {
+                merged[key] = entry;
+            }
+        }
+        for (const [key, entry] of dedupCache) {
+            if (!isFresh(entry, now))
+                continue;
+            const existing = merged[key];
+            if (!existing || existing.timestamp <= entry.timestamp) {
+                merged[key] = entry;
+            }
+        }
+        await fs.mkdir(path.dirname(dedupStateFile), {
+            recursive: true,
+            mode: 0o700,
+        });
+        // pid-suffixed so concurrent servers do not clobber each other's temp.
+        const tmp = `${dedupStateFile}.${process.pid}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(merged), { mode: 0o600 });
+        await fs.rename(tmp, dedupStateFile);
+    })
+        .catch((err) => {
+        console.error(`[x402-dedup] Could not persist ${dedupStateFile}: ${err instanceof Error ? err.message : String(err)}`);
+    });
+    return dedupWriteLock;
+}
 // Cleanup expired dedup entries every 5 minutes
 setInterval(() => {
     const now = Date.now();
     for (const [key, value] of dedupCache) {
-        if (now - value.timestamp > 60000) {
+        if (!isFresh(value, now)) {
             dedupCache.delete(key);
         }
     }
@@ -845,26 +1002,36 @@ export function generateDedupKey(method, url, params, data) {
     return createHash('sha256').update(payload).digest('hex');
 }
 /**
- * Check if a request was recently processed (within 60s)
+ * Check if a request was recently processed (within X402_DEDUP_TTL_MS).
+ *
+ * Loads persisted entries first so a payment broadcast before a server restart
+ * still suppresses the retry that follows it.
+ *
  * @returns txid if duplicate found, null otherwise
  */
-export function checkDedupCache(key) {
+export async function checkDedupCache(key) {
+    await ensureDedupLoaded();
     const cached = dedupCache.get(key);
     if (!cached) {
         return null;
     }
     const now = Date.now();
-    if (now - cached.timestamp > 60000) {
+    if (!isFresh(cached, now)) {
         dedupCache.delete(key);
         return null;
     }
     return cached.txid;
 }
 /**
- * Record a transaction in the dedup cache
+ * Record a transaction in the dedup cache and persist it.
+ *
+ * Awaits the write so the entry survives a crash immediately after a payment —
+ * the window where losing it costs a duplicate payment.
  */
-export function recordTransaction(key, txid) {
+export async function recordTransaction(key, txid) {
+    await ensureDedupLoaded();
     dedupCache.set(key, { txid, timestamp: Date.now() });
+    await persistDedupCache();
 }
 /**
  * Check if account has sufficient balance to pay for x402 endpoint.