sorokeep 1.0.0

package/dist/core/decoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decoder.js","sourceRoot":"","sources":["../../src/core/decoder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAQnE,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7C,MAAM,GAAG,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAEvC,IAAI,GAAG,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,eAAe,CAAC,YAAY,EAAE,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;IACnD,CAAC;IAED,MAAM,YAAY,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;IACxC,MAAM,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,YAAY,CAAC,QAAQ,EAAE,CAAC,CAAC;IACvE,MAAM,UAAU,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;IAE9C,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAG,EAAE,CAAC;IACpC,IAAI,MAAW,CAAC;IAChB,IAAI,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,SAAS,CAAC,4BAA4B,EAAE,EAAE,CAAC;QACvE,MAAM,GAAG,kBAAkB,CAAC;IAC9B,CAAC;SAAM,CAAC;QACN,IAAI,CAAC;YACH,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;QACnC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,GAAG,SAAS,CAAC;QACrB,CAAC;IACH,CAAC;IAED,MAAM,cAAc,GAAG,YAAY,CAAC,UAAU,EAAE,CAAC;IACjD,IAAI,UAAU,GAAG,SAAS,CAAC;IAC3B,IAAI,cAAc,CAAC,KAAK,KAAK,GAAG,CAAC,sBAAsB,CAAC,UAAU,EAAE,CAAC,KAAK,EAAE,CAAC;QAC3E,UAAU,GAAG,YAAY,CAAC;IAC5B,CAAC;SAAM,IAAI,cAAc,CAAC,KAAK,KAAK,GAAG,CAAC,sBAAsB,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,CAAC;QACjF,UAAU,GAAG,WAAW,CAAC;IAC3B,CAAC;IAED,OAAO;QACL,UAAU;QACV,MAAM;QACN,UAAU;KACX,CAAC;AACJ,CAAC"}

package/dist/core/discovery.d.ts

@@ -0,0 +1,38 @@
+import type Database from "better-sqlite3";
+export interface DiscoveryResult {
+    /** Contract ID that was scanned. */
+    contractId: string;
+    /** Number of new storage keys discovered. */
+    newKeysDiscovered: number;
+    /** Total transactions scanned. */
+    transactionsScanned: number;
+    /** Error message if discovery failed. */
+    error?: string;
+}
+export interface BatchDiscoveryResult {
+    /** Total contracts scanned. */
+    contractsScanned: number;
+    /** Total new keys discovered across all contracts. */
+    totalNewKeys: number;
+    /** Per-contract results. */
+    results: DiscoveryResult[];
+    /** Errors that occurred during discovery. */
+    errors: string[];
+}
+/**
+ * Discover new storage keys for a contract by scanning recent transactions.
+ *
+ * Uses the Stellar RPC `getEvents` endpoint to find contract invocation events,
+ * then extracts ledger keys from the event data to discover persistent and
+ * temporary storage entries that the contract has touched.
+ *
+ * This is Layer 2 of the discovery architecture — it learns keys over time
+ * from observed contract activity.
+ */
+export declare function discoverStorageKeys(db: Database.Database, contractId: string, network: string, rpcUrl?: string): Promise<DiscoveryResult>;
+/**
+ * Run discovery for all registered contracts on a network.
+ * Called by the daemon as an optional step after the monitor cycle.
+ */
+export declare function runBatchDiscovery(db: Database.Database, network: string, rpcUrl?: string): Promise<BatchDiscoveryResult>;
+//# sourceMappingURL=discovery.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/core/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAS3C,MAAM,WAAW,eAAe;IAC5B,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,6CAA6C;IAC7C,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kCAAkC;IAClC,mBAAmB,EAAE,MAAM,CAAC;IAC5B,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACjC,+BAA+B;IAC/B,gBAAgB,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,YAAY,EAAE,MAAM,CAAC;IACrB,4BAA4B;IAC5B,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,6CAA6C;IAC7C,MAAM,EAAE,MAAM,EAAE,CAAC;CACpB;AAWD;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACrC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CAsK1B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,CAAC,CA4B/B"}

package/dist/core/discovery.js

@@ -0,0 +1,208 @@
+import { rpc, xdr, StrKey } from "@stellar/stellar-sdk";
+import { getEntriesForContract, upsertEntry, getAllContracts } from "../db/repositories.js";
+import { getLogger } from "../logging/index.js";
+const logger = getLogger().child({ component: "Discovery" });
+// ─── RPC URLs ──────────────────────────────────────────────────────────────────
+const RPC_URLS = {
+    testnet: "https://soroban-testnet.stellar.org",
+    mainnet: "https://mainnet.sorobanrpc.com",
+};
+// ─── Core implementation ──────────────────────────────────────────────────────
+/**
+ * Discover new storage keys for a contract by scanning recent transactions.
+ *
+ * Uses the Stellar RPC `getEvents` endpoint to find contract invocation events,
+ * then extracts ledger keys from the event data to discover persistent and
+ * temporary storage entries that the contract has touched.
+ *
+ * This is Layer 2 of the discovery architecture — it learns keys over time
+ * from observed contract activity.
+ */
+export async function discoverStorageKeys(db, contractId, network, rpcUrl) {
+    const result = {
+        contractId,
+        newKeysDiscovered: 0,
+        transactionsScanned: 0,
+    };
+    const url = rpcUrl ?? RPC_URLS[network];
+    if (!url) {
+        result.error = `Unknown network "${network}"`;
+        return result;
+    }
+    try {
+        const server = new rpc.Server(url);
+        // Get the latest ledger to set up the event window
+        const health = await server.getHealth();
+        const latestLedger = health.latestLedger ?? 0;
+        if (latestLedger === 0) {
+            result.error = "Could not determine latest ledger";
+            return result;
+        }
+        // Look back ~1 hour of ledgers (approximately 655 ledgers at 5.5s/ledger)
+        // The RPC limits event lookback, so we use a reasonable window
+        const startLedger = Math.max(1, latestLedger - 655);
+        // Get existing entry keys so we can identify new ones
+        const existingEntries = getEntriesForContract(db, contractId);
+        const existingKeys = new Set(existingEntries.map(e => e.entry_key_xdr));
+        // Fetch events for this contract with cursor-based pagination
+        const allEvents = [];
+        let cursor;
+        while (true) {
+            const request = {
+                filters: [
+                    {
+                        type: "contract",
+                        contractIds: [contractId],
+                    },
+                ],
+                limit: 100,
+            };
+            if (cursor) {
+                request.pagination = { cursor };
+            }
+            else {
+                request.startLedger = startLedger;
+            }
+            const page = await server.getEvents(request);
+            if (page.events && page.events.length > 0) {
+                allEvents.push(...page.events);
+            }
+            // Continue if there's a cursor for the next page
+            if (page.cursor && page.events && page.events.length === 100) {
+                cursor = page.cursor;
+            }
+            else {
+                break;
+            }
+        }
+        const txHashes = new Set();
+        for (const event of allEvents) {
+            if (event.txHash) {
+                txHashes.add(event.txHash);
+            }
+        }
+        if (txHashes.size === 0) {
+            logger.debug(`No events/transactions found for ${contractId} since ledger ${startLedger}`);
+            return result;
+        }
+        result.transactionsScanned = txHashes.size;
+        const rawContract = Buffer.from(contractId, "hex").length === 32
+            ? Buffer.from(contractId, "hex")
+            : decodeContractId(contractId);
+        for (const txHash of txHashes) {
+            try {
+                const txResponse = await server.getTransaction(txHash);
+                if (!txResponse.envelopeXdr) {
+                    continue; // Skip if no envelope
+                }
+                // Parse envelope
+                // For mock compatibility, handle if envelopeXdr is already an object or a base64 string
+                const env = typeof txResponse.envelopeXdr === 'string'
+                    ? xdr.TransactionEnvelope.fromXDR(txResponse.envelopeXdr, "base64")
+                    : txResponse.envelopeXdr;
+                let innerTx;
+                if (env.switch().name === 'envelopeTypeTx') {
+                    innerTx = env.v1().tx();
+                }
+                else if (env.switch().name === 'envelopeTypeTxFeeBump') {
+                    innerTx = env.feeBump().tx().innerTx().v1().tx();
+                }
+                if (!innerTx)
+                    continue;
+                const ext = innerTx.ext();
+                if (ext.switch().value !== 1)
+                    continue;
+                const sorobanData = ext.v1().sorobanData();
+                const footprint = sorobanData.resources().footprint();
+                const keys = [...footprint.readOnly(), ...footprint.readWrite()];
+                for (const key of keys) {
+                    if (key.switch().name === 'contractData') {
+                        const contractData = key.contractData();
+                        const contractAddr = contractData.contract();
+                        // Check if key belongs to our contract
+                        if (contractAddr.switch().name === 'scAddressTypeContract') {
+                            const addrRaw = contractAddr.contractId();
+                            // Compare raw contract address
+                            if (Buffer.compare(Buffer.from(addrRaw), Buffer.from(rawContract)) === 0) {
+                                const keyXdr = key.toXDR("base64");
+                                if (!existingKeys.has(keyXdr)) {
+                                    existingKeys.add(keyXdr);
+                                    // Identify type (persistent, temporary, instance)
+                                    let entryType = "persistent";
+                                    if (contractData.durability().name === "temporary")
+                                        entryType = "temporary";
+                                    if (contractData.key().switch().name === "scvLedgerKeyContractInstance")
+                                        entryType = "instance";
+                                    upsertEntry(db, {
+                                        contract_id: contractId,
+                                        entry_key_xdr: keyXdr,
+                                        entry_type: entryType,
+                                        label: `Discovered (footprint)`,
+                                        live_until_ledger: 0, // We could fetch from getLedgerEntries if we want TTL, but we can do that in a sync pass
+                                        last_modified_ledger: 0,
+                                        discovery_source: "footprint",
+                                    });
+                                    result.newKeysDiscovered++;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+            catch (err) {
+                logger.debug(`Failed to parse transaction footprint for ${contractId} (tx: ${txHash}): ${err}`);
+            }
+        }
+        logger.debug(`Discovery for ${contractId}: scanned ${result.transactionsScanned} transactions, ` +
+            `found ${result.newKeysDiscovered} new keys`);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        result.error = message;
+        logger.error(`Discovery failed for ${contractId}: ${message}`, err);
+    }
+    return result;
+}
+/**
+ * Run discovery for all registered contracts on a network.
+ * Called by the daemon as an optional step after the monitor cycle.
+ */
+export async function runBatchDiscovery(db, network, rpcUrl) {
+    const batchResult = {
+        contractsScanned: 0,
+        totalNewKeys: 0,
+        results: [],
+        errors: [],
+    };
+    const contracts = getAllContracts(db).filter(c => c.network === network);
+    for (const contract of contracts) {
+        batchResult.contractsScanned++;
+        try {
+            const result = await discoverStorageKeys(db, contract.id, network, rpcUrl);
+            batchResult.results.push(result);
+            batchResult.totalNewKeys += result.newKeysDiscovered;
+            if (result.error) {
+                batchResult.errors.push(`${contract.id}: ${result.error}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            batchResult.errors.push(`${contract.id}: ${message}`);
+        }
+    }
+    return batchResult;
+}
+// ─── Private helpers ──────────────────────────────────────────────────────────
+/**
+ * Decode a Stellar contract ID (C...) to raw 32-byte buffer.
+ */
+function decodeContractId(contractId) {
+    try {
+        return Buffer.from(StrKey.decodeContract(contractId));
+    }
+    catch {
+        // Fallback: assume hex
+        return Buffer.from(contractId, "hex");
+    }
+}
+//# sourceMappingURL=discovery.js.map

package/dist/core/discovery.js.map

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

package/dist/core/extension.d.ts

@@ -0,0 +1,83 @@
+import type Database from "better-sqlite3";
+/**
+ * Maximum number of auto-extension transactions allowed per contract per hour.
+ * Prevents runaway fee submissions under extreme network load (issue #142).
+ */
+export declare const HOURLY_RATE_LIMIT = 5;
+/**
+ * Check whether the given contract has reached its hourly auto-extension rate limit.
+ *
+ * Queries `extension_history` for records within the last 60 minutes and
+ * compares the count against `limit` (default: HOURLY_RATE_LIMIT).
+ *
+ * @param db - The SQLite database connection.
+ * @param contractId - The contract to check.
+ * @param limit - Maximum allowed extensions per hour (defaults to HOURLY_RATE_LIMIT).
+ * @returns `true` when the contract is rate-limited; `false` otherwise.
+ */
+export declare function isRateLimited(db: import("better-sqlite3").Database, contractId: string, limit?: number): boolean;
+export interface ExtensionResult {
+    success: boolean;
+    contractId: string;
+    entriesExtended: number;
+    txHash?: string;
+    ledger?: number;
+    error?: string;
+    /** Estimated fee in stroops (from simulation, before submission). */
+    estimatedFee?: number;
+    /** Actual fee charged in stroops (from submitted transaction result). */
+    feeCharged?: number;
+    /** CPU instructions consumed by the transaction. */
+    cpuInsns?: number;
+    memBytes?: number;
+    /** Read footprint size in bytes. */
+    readBytes?: number;
+    /** Write footprint size in bytes. */
+    writeBytes?: number;
+    /** Whether resource usage spiked. */
+    isAnomaly?: boolean;
+    anomalyDetails?: string;
+}
+export interface AutoExtensionResult {
+    contractsChecked: number;
+    contractsExtended: number;
+    entriesExtended: number;
+    errors: string[];
+    extensions: Array<{
+        contractId: string;
+        txHash: string;
+        entriesExtended: number;
+        ledger: number;
+        isAnomaly?: boolean;
+        anomalyDetails?: string;
+    }>;
+}
+export interface RestoreResult {
+    success: boolean;
+    contractId: string;
+    entriesRestored: number;
+    txHash?: string;
+    ledger?: number;
+    error?: string;
+    /** Estimated fee in stroops (from simulation, before submission). */
+    estimatedFee?: number;
+    cpuInsns?: number;
+    memBytes?: number;
+    minResourceFee?: number;
+    /** Fee charged in stroops. */
+    feeCharged?: number;
+}
+export declare function simulateExtension(db: Database.Database, contractId: string, entryKeyXdrs: string[], extendToLedgers: number, sourcePublicKey: string, rpcUrl?: string): Promise<ExtensionResult>;
+export declare function extendEntries(db: Database.Database, contractId: string, entryKeyXdrs: string[], extendToLedgers: number, secretKey: string, rpcUrl?: string, sponsorSecret?: string): Promise<ExtensionResult>;
+export declare function runAutoExtensions(db: Database.Database, network: string, rpcUrl?: string, sponsorSecret?: string): Promise<AutoExtensionResult>;
+export declare function simulateRestore(db: Database.Database, contractId: string, entryKeyXdrs: string[], sourcePublicKey: string, rpcUrl?: string): Promise<RestoreResult>;
+export declare function restoreEntries(db: Database.Database, contractId: string, entryKeyXdrs: string[], secretKey: string, rpcUrl?: string): Promise<RestoreResult>;
+/**
+ * Resolve a secret key from a keypair_source string.
+ * Supports:
+ *   - "env:VAR_NAME" — reads from environment variable
+ *   - "vault:<secret_path>" — reads from HashiCorp Vault (KV v1/v2)
+ *   - Direct secret key string starting with "S" (56 chars)
+ */
+export declare function resolveSecretKey(source: string | null): Promise<string | null>;
+//# sourceMappingURL=extension.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../src/core/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AA4B3C;;;GAGG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CACzB,EAAE,EAAE,OAAO,gBAAgB,EAAE,QAAQ,EACrC,UAAU,EAAE,MAAM,EAClB,KAAK,SAAoB,GAC1B,OAAO,CAGT;AAKD,MAAM,WAAW,eAAe;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oDAAoD;IAEpD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qCAAqC;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qCAAqC;IAErC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,mBAAmB;IAChC,gBAAgB,EAAE,MAAM,CAAC;IACzB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,UAAU,EAAE,KAAK,CAAC;QACd,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,EAAE,MAAM,CAAC;QACxB,MAAM,EAAE,MAAM,CAAC;QACf,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,cAAc,CAAC,EAAE,MAAM,CAAC;KAC3B,CAAC,CAAC;CACN;AAED,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8BAA8B;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CAEvB;AAED,wBAAsB,iBAAiB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,eAAe,EAAE,MAAM,EACvB,eAAe,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CA+B1B;AAED,wBAAsB,aAAa,CAC/B,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,eAAe,EAAE,MAAM,EACvB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,eAAe,CAAC,CA+H1B;AAED,wBAAsB,iBAAiB,CACnC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,OAAO,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,EACf,aAAa,CAAC,EAAE,MAAM,GACvB,OAAO,CAAC,mBAAmB,CAAC,CAyJ9B;AAED,wBAAsB,eAAe,CACjC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,eAAe,EAAE,MAAM,EACvB,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CAmBxB;AAED,wBAAsB,cAAc,CAChC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EACrB,UAAU,EAAE,MAAM,EAClB,YAAY,EAAE,MAAM,EAAE,EACtB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,aAAa,CAAC,CA8ExB;AAID;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiDpF"}