sorokeep 1.0.0

package/dist/core/vault.d.ts

@@ -0,0 +1,37 @@
+export interface VaultConfig {
+    url: string;
+    token: string;
+    namespace?: string;
+}
+export declare class VaultAuthError extends Error {
+    constructor(message?: string);
+}
+export declare class VaultSecretNotFoundError extends Error {
+    constructor(secretPath: string);
+}
+export declare class VaultSecretError extends Error {
+    constructor(message: string);
+}
+/**
+ * VaultResolver - Retrieve Stellar secret keys dynamically from HashiCorp Vault
+ *
+ * Supports KV v1 and KV v2 secret engines.
+ *
+ * Secret lookup order for field names:
+ *   secret_key, private_key, secret, value, stellar_secret, key
+ *
+ * You can also specify a custom field with a fragment: vault:secret/data/foo#my_field
+ */
+export declare class VaultResolver {
+    private url;
+    private token;
+    private namespace?;
+    constructor(config: VaultConfig);
+    /**
+     * Fetch a Stellar secret key from Vault
+     * @param secretPath Vault secret path, optionally with #field suffix
+     * @returns Stellar secret key string (starts with S)
+     */
+    getSecret(secretPath: string): Promise<string>;
+}
+//# sourceMappingURL=vault.d.ts.map

package/dist/core/vault.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/core/vault.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,WAAW;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,cAAe,SAAQ,KAAK;gBACzB,OAAO,GAAE,MAAsC;CAI9D;AAED,qBAAa,wBAAyB,SAAQ,KAAK;gBACnC,UAAU,EAAE,MAAM;CAIjC;AAED,qBAAa,gBAAiB,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI9B;AAED;;;;;;;;;GASG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,SAAS,CAAC,CAAS;gBAEf,MAAM,EAAE,WAAW;IAa/B;;;;OAIG;IACG,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAmIvD"}

package/dist/core/vault.js

@@ -0,0 +1,179 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { getLogger } from "../logging/index.js";
+const logger = getLogger().child({ component: "VaultResolver" });
+export class VaultAuthError extends Error {
+    constructor(message = "Vault authentication failed") {
+        super(message);
+        this.name = "VaultAuthError";
+    }
+}
+export class VaultSecretNotFoundError extends Error {
+    constructor(secretPath) {
+        super(`Secret not found in Vault at path: ${secretPath}`);
+        this.name = "VaultSecretNotFoundError";
+    }
+}
+export class VaultSecretError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "VaultSecretError";
+    }
+}
+/**
+ * VaultResolver - Retrieve Stellar secret keys dynamically from HashiCorp Vault
+ *
+ * Supports KV v1 and KV v2 secret engines.
+ *
+ * Secret lookup order for field names:
+ *   secret_key, private_key, secret, value, stellar_secret, key
+ *
+ * You can also specify a custom field with a fragment: vault:secret/data/foo#my_field
+ */
+export class VaultResolver {
+    url;
+    token;
+    namespace;
+    constructor(config) {
+        if (!config.url) {
+            throw new VaultSecretError("Vault URL is required");
+        }
+        if (!config.token) {
+            throw new VaultAuthError("Vault token is required");
+        }
+        // Normalize URL (strip trailing slash)
+        this.url = config.url.replace(/\/$/, "");
+        this.token = config.token;
+        this.namespace = config.namespace;
+    }
+    /**
+     * Fetch a Stellar secret key from Vault
+     * @param secretPath Vault secret path, optionally with #field suffix
+     * @returns Stellar secret key string (starts with S)
+     */
+    async getSecret(secretPath) {
+        // Parse field fragment
+        let path = secretPath;
+        let fieldName = null;
+        const hashIdx = secretPath.indexOf("#");
+        if (hashIdx !== -1) {
+            path = secretPath.slice(0, hashIdx);
+            fieldName = secretPath.slice(hashIdx + 1);
+        }
+        // Strip leading slash
+        if (path.startsWith("/")) {
+            path = path.slice(1);
+        }
+        const url = `${this.url}/v1/${path}`;
+        const headers = {
+            "X-Vault-Token": this.token,
+            "Accept": "application/json",
+        };
+        if (this.namespace) {
+            headers["X-Vault-Namespace"] = this.namespace;
+        }
+        let res;
+        try {
+            res = await fetch(url, { headers });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.error(`Vault request failed: ${message}`);
+            throw new VaultSecretError(`Vault request failed: ${message}`);
+        }
+        if (!res.ok) {
+            if (res.status === 403 || res.status === 401) {
+                throw new VaultAuthError(`Vault authentication failed (${res.status})`);
+            }
+            if (res.status === 404) {
+                throw new VaultSecretNotFoundError(path);
+            }
+            let body = "";
+            try {
+                body = await res.text();
+            }
+            catch { /* ignore */ }
+            throw new VaultSecretError(`Vault request failed with status ${res.status}: ${body}`);
+        }
+        let json;
+        try {
+            json = await res.json();
+        }
+        catch (err) {
+            throw new VaultSecretError("Failed to parse Vault response as JSON");
+        }
+        // KV v2: data.data.{field}
+        // KV v1: data.{field}
+        let secretData;
+        if (json?.data?.data && typeof json.data.data === "object") {
+            secretData = json.data.data;
+        }
+        else if (json?.data && typeof json.data === "object") {
+            secretData = json.data;
+        }
+        if (!secretData) {
+            throw new VaultSecretError(`No secret data found at Vault path: ${path}`);
+        }
+        let secretValue;
+        if (fieldName) {
+            secretValue = secretData[fieldName];
+            if (secretValue === undefined) {
+                throw new VaultSecretError(`Field '${fieldName}' not found in Vault secret at path: ${path}`);
+            }
+        }
+        else {
+            // Try common field names in order
+            const candidates = [
+                "secret_key",
+                "private_key",
+                "secret",
+                "value",
+                "stellar_secret",
+                "key",
+            ];
+            for (const key of candidates) {
+                if (typeof secretData[key] === "string") {
+                    secretValue = secretData[key];
+                    break;
+                }
+            }
+            // Fallback: if there's exactly one string field that looks like a Stellar secret, use it
+            if (!secretValue) {
+                const stringEntries = Object.entries(secretData).filter(([, v]) => typeof v === "string");
+                if (stringEntries.length === 1) {
+                    const first = stringEntries[0];
+                    if (first)
+                        secretValue = first[1];
+                }
+                else {
+                    // Try to find any Stellar-looking secret
+                    const stellarEntry = stringEntries.find(([, v]) => isStellarSecret(v));
+                    if (stellarEntry) {
+                        secretValue = stellarEntry[1];
+                    }
+                }
+            }
+        }
+        if (!secretValue || typeof secretValue !== "string") {
+            throw new VaultSecretError(`No valid secret key found in Vault response at path: ${path}. ` +
+                `Expected one of: secret_key, private_key, secret, value, stellar_secret, key`);
+        }
+        if (!isStellarSecret(secretValue)) {
+            throw new VaultSecretError(`Secret retrieved from Vault is not a valid Stellar secret key format. ` +
+                `Expected 56-character string starting with 'S', got: ${maskSecret(secretValue)}`);
+        }
+        logger.debug(`Successfully resolved secret from Vault path: ${path}`);
+        return secretValue;
+    }
+}
+/**
+ * Check if a string looks like a Stellar secret key
+ */
+function isStellarSecret(value) {
+    return typeof value === "string" && value.startsWith("S") && value.length === 56;
+}
+function maskSecret(secret) {
+    if (secret.length <= 8)
+        return "***";
+    return `${secret.slice(0, 4)}...${secret.slice(-4)}`;
+}
+//# sourceMappingURL=vault.js.map

package/dist/core/vault.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault.js","sourceRoot":"","sources":["../../src/core/vault.ts"],"names":[],"mappings":"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"}

package/dist/core/watch.d.ts

@@ -0,0 +1,36 @@
+import type Database from "better-sqlite3";
+import { ContractInstanceResult, SorokeepLedgerEntryResult } from "../rpc/client.js";
+export interface WatchOptions {
+    contractId: string;
+    network: string;
+    name?: string;
+    rpcUrl?: string;
+    storageKeys?: string[];
+    pollIntervalSeconds?: number;
+    /**
+     * When true, skip the introspection cache and always fetch fresh data from
+     * the RPC. Useful for manual `watch` commands where the user expects an
+     * immediate refresh.  Defaults to false.
+     */
+    forceRefresh?: boolean;
+    noIntrospection?: boolean;
+}
+export type WatchResult = {
+    success: true;
+    contractId: string;
+    instance: ContractInstanceResult;
+    wasm: SorokeepLedgerEntryResult | null;
+    wasmWarning?: string;
+    /** True when the result was served from the introspection cache (no RPC call). */
+    fromCache?: boolean;
+} | {
+    success: false;
+    contractId: string;
+    error: string;
+};
+/**
+ * Core logic to discover and register a contract and its key entries.
+ * - This is `Layer 1` of the architecture.
+ */
+export declare function watchContract(db: Database.Database, options: WatchOptions): Promise<WatchResult>;
+//# sourceMappingURL=watch.d.ts.map

package/dist/core/watch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.d.ts","sourceRoot":"","sources":["../../src/core/watch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAoB,sBAAsB,EAAE,yBAAyB,EAAE,MAAM,kBAAkB,CAAC;AAavG,MAAM,WAAW,YAAY;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,MAAM,WAAW,GACjB;IACF,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,sBAAsB,CAAC;IACjC,IAAI,EAAE,yBAAyB,GAAG,IAAI,CAAC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,SAAS,CAAC,EAAE,OAAO,CAAC;CACvB,GAAG;IACA,OAAO,EAAE,KAAK,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;GAGG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,CAuLtG"}

package/dist/core/watch.js

@@ -0,0 +1,176 @@
+import { StellarRpcClient } from "../rpc/client.js";
+import { insertContract, upsertEntry, updateLastCheckedLedger, getContract, updateLastIntrospectedAt, isIntrospectionCacheValid, } from "../db/repositories.js";
+import { getLogger } from "../logging/index.js";
+const logger = getLogger();
+/**
+ * Core logic to discover and register a contract and its key entries.
+ * - This is `Layer 1` of the architecture.
+ */
+export async function watchContract(db, options) {
+    logger.debug(`Watching contract ${options.contractId} on ${options.network}`);
+    const { contractId, network, name, rpcUrl, storageKeys, forceRefresh = false, pollIntervalSeconds } = options;
+    // Basic Validation
+    if (!contractId.startsWith("C") || contractId.length !== 56) {
+        logger.error(`Invalid Contract ID format: ${contractId}`);
+        return {
+            success: false,
+            contractId,
+            error: "Invalid Contract ID format. Must be a 56-character string starting with 'C'.",
+        };
+    }
+    const client = new StellarRpcClient(network, rpcUrl);
+    try {
+        // 0. Check if already registered on a different network
+        const existing = getContract(db, contractId);
+        if (existing && existing.network !== network) {
+            logger.warn(`Contract ${contractId} is already registered on ${existing.network}. To watch on ${network}, unwatch it first.`);
+            return {
+                success: false,
+                contractId,
+                error: `Contract ${contractId} is already registered on ${existing.network}. To watch on ${network}, unwatch it first.`,
+            };
+        }
+        // ── Introspection cache check ─────────────────────────────────────────
+        // If the contract has been introspected recently (within 24 h) and the
+        // caller did not request a forced refresh, skip the RPC calls entirely
+        // and return the cached result.
+        if (!forceRefresh && isIntrospectionCacheValid(db, contractId)) {
+            logger.debug(`Contract ${contractId}: introspection cache is valid — skipping RPC calls`);
+            // Build a minimal success result from cached DB data.
+            // We return success=true without real instance/wasm objects so that
+            // callers (CLI, daemon) know the operation succeeded. The actual
+            // entry data remains accurate in the DB from the last introspection.
+            return {
+                success: true,
+                contractId,
+                // Provide stub values — callers that need live RPC data should
+                // use forceRefresh=true.
+                instance: {
+                    entryKeyXdr: "",
+                    latestLedger: 0,
+                    liveUntilLedgerSeq: 0,
+                    lastModifiedLedgerSeq: 0,
+                    remainingTTL: 0,
+                    executableType: "cached",
+                    wasmHash: existing?.wasm_hash ?? null,
+                },
+                wasm: null,
+                fromCache: true,
+            };
+        }
+        // 1. Fetch Contract Instance Entry
+        const instanceEntry = await client.getContractInstanceEntry(contractId);
+        if (!instanceEntry) {
+            return {
+                success: false,
+                contractId,
+                error: `Contract ${contractId} not found on ${network}.`,
+            };
+        }
+        // 2. Fetch WASM code entry if applicable
+        let wasmEntry = null;
+        let wasmWarning;
+        if (instanceEntry.wasmHash && !options.noIntrospection) {
+            wasmEntry = await client.getWasmCodeEntry(instanceEntry.wasmHash);
+            if (!wasmEntry) {
+                wasmWarning = `WASM entry for hash ${instanceEntry.wasmHash} not found. It might be archived.`;
+            }
+        }
+        // 3. Fetch Manual Storage Keys if provided
+        const extraEntries = [];
+        if (storageKeys && storageKeys.length > 0) {
+            const ttls = await client.getEntryTTLs(storageKeys);
+            extraEntries.push(...ttls.entries);
+        }
+        // 3.5. Introspection: Fetch monitored keys if contract supports it
+        const introspectedEntries = [];
+        if (!options.noIntrospection) {
+            try {
+                const keys = await client.getMonitoredKeys(contractId);
+                if (keys.length > 0) {
+                    const ttls = await client.getEntryTTLs(keys);
+                    introspectedEntries.push(...ttls.entries);
+                }
+            }
+            catch (error) {
+                logger.debug(`Introspection skipped for ${contractId}: ${error}`);
+            }
+        }
+        // 4. Store in Database
+        // Note: insertContract uses ON CONFLICT(id) DO UPDATE
+        insertContract(db, {
+            id: contractId,
+            name: name,
+            network: network,
+            wasm_hash: instanceEntry.wasmHash ?? undefined,
+            poll_interval_seconds: pollIntervalSeconds ?? null,
+        });
+        // Store Instance Entry
+        upsertEntry(db, {
+            contract_id: contractId,
+            entry_key_xdr: instanceEntry.entryKeyXdr,
+            entry_type: "instance",
+            label: "Contract Instance",
+            live_until_ledger: instanceEntry.liveUntilLedgerSeq,
+            last_modified_ledger: instanceEntry.lastModifiedLedgerSeq,
+            discovery_source: "deterministic",
+        });
+        // Store WASM Entry if found
+        if (wasmEntry) {
+            upsertEntry(db, {
+                contract_id: contractId,
+                entry_key_xdr: wasmEntry.entryKeyXdr,
+                entry_type: "wasm",
+                label: "WASM Code",
+                live_until_ledger: wasmEntry.liveUntilLedgerSeq,
+                last_modified_ledger: wasmEntry.lastModifiedLedgerSeq,
+                discovery_source: "deterministic",
+            });
+        }
+        // Store Manual Storage Entries
+        for (const entry of extraEntries) {
+            upsertEntry(db, {
+                contract_id: contractId,
+                entry_key_xdr: entry.entryKeyXdr,
+                entry_type: "persistent", // Defaulting to persistent for manual keys
+                label: "Manual Storage Entry",
+                live_until_ledger: entry.liveUntilLedgerSeq,
+                last_modified_ledger: entry.lastModifiedLedgerSeq,
+                discovery_source: "manual",
+            });
+        }
+        // Store Introspected Entries
+        for (const entry of introspectedEntries) {
+            upsertEntry(db, {
+                contract_id: contractId,
+                entry_key_xdr: entry.entryKeyXdr,
+                entry_type: "persistent", // Defaulting to persistent for introspected keys
+                label: "Introspected Storage Entry",
+                live_until_ledger: entry.liveUntilLedgerSeq,
+                last_modified_ledger: entry.lastModifiedLedgerSeq,
+                discovery_source: "introspection",
+            });
+        }
+        // Update last checked ledger
+        updateLastCheckedLedger(db, contractId, instanceEntry.latestLedger);
+        // ── Record successful introspection in the cache ───────────────────────
+        updateLastIntrospectedAt(db, contractId, new Date().toISOString());
+        return {
+            success: true,
+            contractId,
+            instance: instanceEntry,
+            wasm: wasmEntry,
+            wasmWarning,
+            fromCache: false,
+        };
+    }
+    catch (error) {
+        logger.error(`Error watching contract ${contractId}: ${error.message}`, error);
+        return {
+            success: false,
+            contractId,
+            error: error.message,
+        };
+    }
+}
+//# sourceMappingURL=watch.js.map

package/dist/core/watch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch.js","sourceRoot":"","sources":["../../src/core/watch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAqD,MAAM,kBAAkB,CAAC;AACvG,OAAO,EACH,cAAc,EACd,WAAW,EACX,uBAAuB,EACvB,WAAW,EACX,wBAAwB,EACxB,yBAAyB,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAC,SAAS,EAAC,MAAM,qBAAqB,CAAC;AAE9C,MAAM,MAAM,GAAG,SAAS,EAAE,CAAA;AAiC1B;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,EAAqB,EAAE,OAAqB;IAC5E,MAAM,CAAC,KAAK,CAAC,qBAAqB,OAAO,CAAC,UAAU,OAAO,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9E,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,YAAY,GAAG,KAAK,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAC;IAE9G,mBAAmB;IACnB,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC1D,MAAM,CAAC,KAAK,CAAC,+BAA+B,UAAU,EAAE,CAAC,CAAC;QAC1D,OAAO;YACH,OAAO,EAAE,KAAK;YACd,UAAU;YACV,KAAK,EAAE,8EAA8E;SACxF,CAAC;IACN,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAErD,IAAI,CAAC;QACD,wDAAwD;QACxD,MAAM,QAAQ,GAAG,WAAW,CAAC,EAAE,EAAE,UAAU,CAAC,CAAC;QAC7C,IAAI,QAAQ,IAAI,QAAQ,CAAC,OAAO,KAAK,OAAO,EAAE,CAAC;YAC3C,MAAM,CAAC,IAAI,CAAC,YAAY,UAAU,6BAA6B,QAAQ,CAAC,OAAO,iBAAiB,OAAO,qBAAqB,CAAC,CAAC;YAC9H,OAAO;gBACH,OAAO,EAAE,KAAK;gBACd,UAAU;gBACV,KAAK,EAAE,YAAY,UAAU,6BAA6B,QAAQ,CAAC,OAAO,iBAAiB,OAAO,qBAAqB;aAC1H,CAAC;QACN,CAAC;QAED,yEAAyE;QACzE,uEAAuE;QACvE,uEAAuE;QACvE,gCAAgC;QAChC,IAAI,CAAC,YAAY,IAAI,yBAAyB,CAAC,EAAE,EAAE,UAAU,CAAC,EAAE,CAAC;YAC7D,MAAM,CAAC,KAAK,CAAC,YAAY,UAAU,qDAAqD,CAAC,CAAC;YAE1F,sDAAsD;YACtD,oEAAoE;YACpE,iEAAiE;YACjE,qEAAqE;YACrE,OAAO;gBACH,OAAO,EAAE,IAAI;gBACb,UAAU;gBACV,+DAA+D;gBAC/D,yBAAyB;gBACzB,QAAQ,EAAE;oBACN,WAAW,EAAE,EAAE;oBACf,YAAY,EAAE,CAAC;oBACf,kBAAkB,EAAE,CAAC;oBACrB,qBAAqB,EAAE,CAAC;oBACxB,YAAY,EAAE,CAAC;oBACf,cAAc,EAAE,QAAQ;oBACxB,QAAQ,EAAE,QAAQ,EAAE,SAAS,IAAI,IAAI;iBACxC;gBACD,IAAI,EAAE,IAAI;gBACV,SAAS,EAAE,IAAI;aAClB,CAAC;QACN,CAAC;QAED,mCAAmC;QACnC,MAAM,aAAa,GAAG,MAAM,MAAM,CAAC,wBAAwB,CAAC,UAAU,CAAC,CAAC;QACxE,IAAI,CAAC,aAAa,EAAE,CAAC;YACjB,OAAO;gBACH,OAAO,EAAE,KAAK;gBACd,UAAU;gBACV,KAAK,EAAE,YAAY,UAAU,iBAAiB,OAAO,GAAG;aAC3D,CAAC;QACN,CAAC;QAED,yCAAyC;QACzC,IAAI,SAAS,GAAqC,IAAI,CAAC;QACvD,IAAI,WAA+B,CAAC;QAEpC,IAAI,aAAa,CAAC,QAAQ,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;YACrD,SAAS,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;YAClE,IAAI,CAAC,SAAS,EAAE,CAAC;gBACb,WAAW,GAAG,uBAAuB,aAAa,CAAC,QAAQ,mCAAmC,CAAC;YACnG,CAAC;QACL,CAAC;QAED,2CAA2C;QAC3C,MAAM,YAAY,GAAgC,EAAE,CAAC;QACrD,IAAI,WAAW,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxC,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,WAAW,CAAC,CAAC;YACpD,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,CAAC;QAED,mEAAmE;QACnE,MAAM,mBAAmB,GAAgC,EAAE,CAAC;QAC5D,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;YAC3B,IAAI,CAAC;gBACD,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;gBACvD,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAClB,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;oBAC7C,mBAAmB,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC9C,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,MAAM,CAAC,KAAK,CAAC,6BAA6B,UAAU,KAAK,KAAK,EAAE,CAAC,CAAC;YACtE,CAAC;QACL,CAAC;QAED,uBAAuB;QACvB,sDAAsD;QACtD,cAAc,CAAC,EAAE,EAAE;YACf,EAAE,EAAE,UAAU;YACd,IAAI,EAAE,IAAI;YACV,OAAO,EAAE,OAAO;YAChB,SAAS,EAAE,aAAa,CAAC,QAAQ,IAAI,SAAS;YAC9C,qBAAqB,EAAE,mBAAmB,IAAI,IAAI;SACrD,CAAC,CAAC;QAEH,uBAAuB;QACvB,WAAW,CAAC,EAAE,EAAE;YACZ,WAAW,EAAE,UAAU;YACvB,aAAa,EAAE,aAAa,CAAC,WAAW;YACxC,UAAU,EAAE,UAAU;YACtB,KAAK,EAAE,mBAAmB;YAC1B,iBAAiB,EAAE,aAAa,CAAC,kBAAkB;YACnD,oBAAoB,EAAE,aAAa,CAAC,qBAAqB;YACzD,gBAAgB,EAAE,eAAe;SACpC,CAAC,CAAC;QAEH,4BAA4B;QAC5B,IAAI,SAAS,EAAE,CAAC;YACZ,WAAW,CAAC,EAAE,EAAE;gBACZ,WAAW,EAAE,UAAU;gBACvB,aAAa,EAAE,SAAS,CAAC,WAAW;gBACpC,UAAU,EAAE,MAAM;gBAClB,KAAK,EAAE,WAAW;gBAClB,iBAAiB,EAAE,SAAS,CAAC,kBAAkB;gBAC/C,oBAAoB,EAAE,SAAS,CAAC,qBAAqB;gBACrD,gBAAgB,EAAE,eAAe;aACpC,CAAC,CAAC;QACP,CAAC;QAED,+BAA+B;QAC/B,KAAK,MAAM,KAAK,IAAI,YAAY,EAAE,CAAC;YAC/B,WAAW,CAAC,EAAE,EAAE;gBACZ,WAAW,EAAE,UAAU;gBACvB,aAAa,EAAE,KAAK,CAAC,WAAW;gBAChC,UAAU,EAAE,YAAY,EAAE,2CAA2C;gBACrE,KAAK,EAAE,sBAAsB;gBAC7B,iBAAiB,EAAE,KAAK,CAAC,kBAAkB;gBAC3C,oBAAoB,EAAE,KAAK,CAAC,qBAAqB;gBACjD,gBAAgB,EAAE,QAAQ;aAC7B,CAAC,CAAC;QACP,CAAC;QAED,6BAA6B;QAC7B,KAAK,MAAM,KAAK,IAAI,mBAAmB,EAAE,CAAC;YACtC,WAAW,CAAC,EAAE,EAAE;gBACZ,WAAW,EAAE,UAAU;gBACvB,aAAa,EAAE,KAAK,CAAC,WAAW;gBAChC,UAAU,EAAE,YAAY,EAAE,iDAAiD;gBAC3E,KAAK,EAAE,4BAA4B;gBACnC,iBAAiB,EAAE,KAAK,CAAC,kBAAkB;gBAC3C,oBAAoB,EAAE,KAAK,CAAC,qBAAqB;gBACjD,gBAAgB,EAAE,eAAe;aACpC,CAAC,CAAC;QACP,CAAC;QAED,6BAA6B;QAC7B,uBAAuB,CAAC,EAAE,EAAE,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;QAEpE,0EAA0E;QAC1E,wBAAwB,CAAC,EAAE,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;QAEnE,OAAO;YACH,OAAO,EAAE,IAAI;YACb,UAAU;YACV,QAAQ,EAAE,aAAa;YACvB,IAAI,EAAE,SAAS;YACf,WAAW;YACX,SAAS,EAAE,KAAK;SACnB,CAAC;IAEN,CAAC;IAAC,OAAO,KAAU,EAAE,CAAC;QAClB,MAAM,CAAC,KAAK,CAAC,2BAA2B,UAAU,KAAK,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;QAC/E,OAAO;YACH,OAAO,EAAE,KAAK;YACd,UAAU;YACV,KAAK,EAAE,KAAK,CAAC,OAAO;SACvB,CAAC;IACN,CAAC;AACL,CAAC"}

package/dist/daemon/loop.d.ts

@@ -0,0 +1,38 @@
+import type Database from "better-sqlite3";
+import { type MonitorCycleResult } from "../core/monitor.js";
+export interface DaemonOptions {
+    /** Polling interval in milliseconds. Defaults to 300000 (5 minutes). */
+    intervalMs?: number;
+    /** Optional RPC endpoint URL override. */
+    rpcUrl?: string;
+    /** Optional sponsor secret key for auto-extensions */
+    feeSponsorSecret?: string;
+    /** How frequently to run vacuum maintenance. Defaults to 24 hours. */
+    vacuumIntervalMs?: number;
+    /** Called after every cycle with the result (or null + error on failure). */
+    onCycle?: (result: MonitorCycleResult | null, error?: Error) => void;
+}
+/**
+ * Start the monitoring daemon.
+ *
+ * Runs one cycle immediately, then schedules repeating cycles at the
+ * configured interval.  Never rejects — errors from individual cycles
+ * are caught, logged, and forwarded to the optional `onCycle` callback.
+ *
+ * Calling `startDaemon` while a daemon is already running will stop the
+ * previous loop first (kills the old timer), then start fresh.
+ *
+ * Re-entrance guard: if a cycle is still in-flight when the next interval
+ * fires, that tick is skipped silently.
+ */
+export declare function startDaemon(db: Database.Database, network: string, options?: DaemonOptions): Promise<void>;
+/**
+ * Stop the monitoring daemon.
+ *
+ * Clears the interval timer so no further cycles are scheduled.
+ * Idempotent — safe to call multiple times or before `startDaemon`.
+ * Does NOT abort a cycle that is currently in-flight; it will finish
+ * naturally, but no new cycle will be scheduled after it.
+ */
+export declare function stopDaemon(): void;
+//# sourceMappingURL=loop.d.ts.map

package/dist/daemon/loop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/daemon/loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAmB,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAiB9E,MAAM,WAAW,aAAa;IAC1B,wEAAwE;IACxE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,CAAC;CACxE;AAcD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC7B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,aAAa,GACxB,OAAO,CAAC,IAAI,CAAC,CAoBf;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,IAAI,IAAI,CAUjC"}

package/dist/daemon/loop.js

@@ -0,0 +1,169 @@
+import { runMonitorCycle } from "../core/monitor.js";
+import { deliverPendingAlerts } from "../alerts/dispatcher.js";
+import { vacuumDatabase } from "../db/database.js";
+import { aggregateDailyCostSnapshots, getAllContracts } from "../db/repositories.js";
+import { getLogger } from "../logging/index.js";
+// Resolve the child logger lazily so that a runtime reconfiguration of the
+// global logger (e.g. the daemon command's `--log-format json`) is in effect
+// by the time the loop emits its first line.
+let loopLogger = null;
+function logger() {
+    return (loopLogger ??= getLogger().child({ component: "DaemonLoop" }));
+}
+// ─── Module-level state ───────────────────────────────────────────────────────
+const DEFAULT_INTERVAL_MS = 300_000; // 5 minutes
+const DEFAULT_VACUUM_INTERVAL_MS = 24 * 60 * 60 * 1000; // 24 hours
+let intervalHandle = null;
+let cycleInFlight = false;
+let vacuumIntervalMs = DEFAULT_VACUUM_INTERVAL_MS;
+let lastVacuumAt = 0;
+// ─── Core API ─────────────────────────────────────────────────────────────────
+/**
+ * Start the monitoring daemon.
+ *
+ * Runs one cycle immediately, then schedules repeating cycles at the
+ * configured interval.  Never rejects — errors from individual cycles
+ * are caught, logged, and forwarded to the optional `onCycle` callback.
+ *
+ * Calling `startDaemon` while a daemon is already running will stop the
+ * previous loop first (kills the old timer), then start fresh.
+ *
+ * Re-entrance guard: if a cycle is still in-flight when the next interval
+ * fires, that tick is skipped silently.
+ */
+export async function startDaemon(db, network, options) {
+    // Kill any existing loop before starting a new one.
+    stopDaemon();
+    const intervalMs = options?.intervalMs ?? DEFAULT_INTERVAL_MS;
+    vacuumIntervalMs = options?.vacuumIntervalMs ?? DEFAULT_VACUUM_INTERVAL_MS;
+    const rpcUrl = options?.rpcUrl;
+    const onCycle = options?.onCycle;
+    const effectiveIntervalMs = resolvePollIntervalMs(db, network, intervalMs);
+    lastVacuumAt = Date.now();
+    logger().info(`Daemon starting — network: ${network}, interval: ${intervalMs}ms`);
+    // Run the initial cycle immediately.
+    await executeCycle(db, network, rpcUrl, options?.feeSponsorSecret, onCycle);
+    // Schedule repeating cycles.
+    intervalHandle = setInterval(() => {
+        void scheduledTick(db, network, rpcUrl, options?.feeSponsorSecret, onCycle);
+    }, effectiveIntervalMs);
+}
+/**
+ * Stop the monitoring daemon.
+ *
+ * Clears the interval timer so no further cycles are scheduled.
+ * Idempotent — safe to call multiple times or before `startDaemon`.
+ * Does NOT abort a cycle that is currently in-flight; it will finish
+ * naturally, but no new cycle will be scheduled after it.
+ */
+export function stopDaemon() {
+    if (intervalHandle !== null) {
+        clearInterval(intervalHandle);
+        intervalHandle = null;
+        logger().info("Daemon stopped");
+    }
+    // Do NOT reset cycleInFlight here — let executeCycle's finally-block
+    // handle it when the in-flight cycle completes.  Resetting it early
+    // breaks the re-entrance guard if startDaemon() is called before the
+    // old cycle finishes.
+}
+// ─── Private ──────────────────────────────────────────────────────────────────
+/**
+ * Execute a single monitoring cycle with full error isolation.
+ *
+ * Sets the `cycleInFlight` flag to prevent re-entrance, runs the cycle,
+ * invokes the `onCycle` callback, and guarantees that no thrown error
+ * (from the cycle or the callback) can kill the daemon.
+ */
+async function executeCycle(db, network, rpcUrl, feeSponsorSecret, onCycle) {
+    cycleInFlight = true;
+    try {
+        const result = await runMonitorCycle(db, network, rpcUrl, feeSponsorSecret);
+        logger().debug(`Cycle complete — checked: ${result.contractsChecked}, ` +
+            `updated: ${result.entriesUpdated}, ` +
+            `crossed: ${result.thresholdsCrossed}, ` +
+            `resolved: ${result.alertsResolved}, ` +
+            `extended: ${result.extensionsTriggered}, ` +
+            `errors: ${result.errors.length}`);
+        // Step 2: deliver any pending alerts that accumulated during detection.
+        // Errors here are isolated — they must NOT kill the cycle or surface to onCycle.
+        try {
+            const delivery = await deliverPendingAlerts(db, network);
+            if (delivery.attempted > 0) {
+                logger().info(`Delivery — attempted: ${delivery.attempted}, ` +
+                    `delivered: ${delivery.delivered}, failed: ${delivery.failed}`);
+            }
+        }
+        catch (deliveryErr) {
+            // This should never happen (deliverPendingAlerts never throws),
+            // but guard defensively.
+            logger().error("deliverPendingAlerts threw unexpectedly", deliveryErr);
+        }
+        // Step 3: aggregate daily cost snapshots for past extension history.
+        try {
+            aggregateDailyCostSnapshots(db);
+        }
+        catch (snapshotErr) {
+            logger().error("aggregateDailyCostSnapshots threw unexpectedly", snapshotErr);
+        }
+        safeOnCycle(onCycle, result, undefined);
+    }
+    catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        logger().error(`Cycle failed: ${error.message}`, err);
+        safeOnCycle(onCycle, null, error);
+    }
+    finally {
+        cycleInFlight = false;
+    }
+}
+async function scheduledTick(db, network, rpcUrl, feeSponsorSecret, onCycle) {
+    if (cycleInFlight) {
+        logger().debug("Skipping tick — previous cycle still in flight");
+        return;
+    }
+    await runScheduledVacuum(db);
+    await executeCycle(db, network, rpcUrl, feeSponsorSecret, onCycle);
+}
+async function runScheduledVacuum(db) {
+    if (Date.now() - lastVacuumAt < vacuumIntervalMs) {
+        return;
+    }
+    if (db.inTransaction) {
+        logger().info("Skipping scheduled vacuum — database has an active transaction");
+        return;
+    }
+    logger().info("Scheduled maintenance: starting database vacuum");
+    const vacuumed = vacuumDatabase(db);
+    if (vacuumed) {
+        lastVacuumAt = Date.now();
+        logger().info("Scheduled maintenance: database vacuum completed");
+    }
+    else {
+        logger().info("Scheduled maintenance: database vacuum skipped due to busy database");
+    }
+}
+/**
+ * Invoke the onCycle callback without letting it kill the daemon.
+ */
+function safeOnCycle(onCycle, result, error) {
+    if (!onCycle)
+        return;
+    try {
+        onCycle(result, error);
+    }
+    catch (cbErr) {
+        logger().error("onCycle callback threw — ignoring", cbErr);
+    }
+}
+function resolvePollIntervalMs(db, network, fallbackIntervalMs) {
+    const contracts = getAllContracts(db).filter((contract) => contract.network === network);
+    const overrides = contracts
+        .map((contract) => contract.poll_interval_seconds)
+        .filter((value) => typeof value === "number" && value > 0);
+    if (overrides.length === 0) {
+        return fallbackIntervalMs;
+    }
+    return Math.min(...overrides) * 1000;
+}
+//# sourceMappingURL=loop.js.map