@economicagents/graph 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @economicagents/graph
 
-Economic graph for AEP: payments, credit events, credit scoring, and provider recommendations. Synced to SQLite (`graph.db`).
+Economic graph for AEP: sync on-chain payments and credit events into SQLite (`graph.db`), compute credit scores, and provider recommendations.
 
 ## Install
 
@@ -8,15 +8,15 @@ Economic graph for AEP: payments, credit events, credit scoring, and provider re
 pnpm add @economicagents/graph
 ```
 
-From monorepo: `cd packages/graph && pnpm run build`.
+**From a local clone** of [economicagents/AEP](https://github.com/economicagents/AEP): `cd packages/graph && pnpm run build`.
 
 ## Usage
 
 ```bash
-# Via CLI (when installed)
+# Standalone binary when installed
 aep-graph sync
 
-# Via @economicagents/cli (includes graph)
+# Via CLI meta-package
 aep graph sync
 aep analytics <address>
 aep credit-score <address>
@@ -30,26 +30,25 @@ const score = computeCreditScore(graphPath, accountAddress);
 const recs = getRecommendations(graphPath, providers, accountAddress, capability, limit);
 ```
 
-Used by the resolver for recommendation boost (`accountAddress` + `graphPath`).
+The resolver uses `graphPath` + `accountAddress` for recommendation boost.
 
 ## Configuration
 
-- **Graph path:** `~/.aep/graph.db` by default; override via `graphPath` in config
-- **RPC:** Required for sync; `RPC_URL` or config `rpcUrl`
-- **Config:** `~/.aep/config.json`
+- **Graph path:** default `~/.aep/graph.db`; override `graphPath` in `~/.aep/config.json`
+- **RPC:** `RPC_URL` or config `rpcUrl` for `graph sync`
 
 ## Dependencies
 
-Optional: `better-sqlite3` (v12+). Tests fall back to `sql.js` when native bindings unavailable.
+Optional native `better-sqlite3` (v12+); tests fall back to `sql.js` when bindings are unavailable.
 
-## Build & Test
+## Build & test
 
 ```bash
 pnpm run build
 pnpm run test
 ```
 
-## Docs
+## Documentation
 
-- [Cookbook](../../docs/COOKBOOK.md) — Fleet, analytics
-- [Architecture](../../docs/ARCHITECTURE.md) — Graph schema
+- [Cookbook](https://github.com/economicagents/AEP/blob/main/docs/COOKBOOK.md) — Fleet, analytics
+- [Architecture](https://github.com/economicagents/AEP/blob/main/docs/ARCHITECTURE.md) — Graph role in the stack

package/dist/cli.d.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 /**
  * CLI for AEP economic graph sync.
- * Usage: npx aep-graph sync [options]
  */
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;GAGG"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;GAEG"}

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 /**
  * CLI for AEP economic graph sync.
- * Usage: npx aep-graph sync [options]
  */
 import { join } from "path";
 import { homedir } from "os";
 import { existsSync, readFileSync } from "fs";
+import { Command } from "commander";
 import { syncGraph } from "./index.js";
 function getConfigPath() {
     const env = process.env.AEP_CONFIG_PATH;
@@ -29,29 +29,36 @@ function loadConfig() {
     }
     return {};
 }
-async function main() {
-    const args = process.argv.slice(2);
-    const command = args[0] ?? "sync";
+const program = new Command();
+program
+    .name("aep-graph")
+    .description("AEP economic graph: sync on-chain events into local SQLite graph store")
+    .version("0.2.0")
+    .addHelpText("after", `\nExamples:\n  $ aep-graph sync\n  $ aep-graph sync -r https://sepolia.base.org --graph-path ~/.aep/graph\n`);
+program
+    .command("sync")
+    .description("Incremental graph sync (accounts, payments, credit, escrow, splitter, SLA)")
+    .option("-r, --rpc <url>", "JSON-RPC URL", DEFAULT_RPC)
+    .option("--graph-path <path>", "Graph database path", DEFAULT_GRAPH_PATH)
+    .option("--chain-id <id>", "Chain id (overrides config when set)")
+    .action(async (opts) => {
     const config = loadConfig();
-    if (command !== "sync") {
-        console.error("Usage: aep-graph <sync> [options]");
-        console.error("  sync  [--rpc <url>] [--graph-path <path>] [--chain-id <id>]");
-        process.exit(1);
-    }
-    const rpcIndex = args.indexOf("--rpc");
-    const rpcUrl = rpcIndex >= 0 ? args[rpcIndex + 1] : config.rpcUrl ?? DEFAULT_RPC;
-    const pathIndex = args.indexOf("--graph-path");
-    const graphPath = pathIndex >= 0 ? args[pathIndex + 1] : config.graphPath ?? DEFAULT_GRAPH_PATH;
+    const rpcUrl = opts.rpc ?? config.rpcUrl ?? DEFAULT_RPC;
+    const graphPath = opts.graphPath ?? config.graphPath ?? DEFAULT_GRAPH_PATH;
     const factoryAddress = (config.aepAccountFactoryAddress ?? config.factoryAddress);
     if (!factoryAddress || factoryAddress === "0x0000000000000000000000000000000000000000") {
         console.error("Error: factoryAddress or aepAccountFactoryAddress required in config (deploy factory first)");
         process.exit(1);
     }
-    const chainIdArg = args.indexOf("--chain-id");
-    let chainId = chainIdArg >= 0 && args[chainIdArg + 1]
-        ? parseInt(args[chainIdArg + 1], 10)
-        : config.chainId ??
-            parseInt(process.env.AEP_CHAIN_ID ?? process.env.BASE_SEPOLIA_CHAIN_ID ?? "84532", 10);
+    let chainId;
+    if (opts.chainId != null && opts.chainId !== "") {
+        chainId = parseInt(String(opts.chainId), 10);
+    }
+    else {
+        chainId =
+            config.chainId ??
+                parseInt(process.env.AEP_CHAIN_ID ?? process.env.BASE_SEPOLIA_CHAIN_ID ?? "84532", 10);
+    }
     if (Number.isNaN(chainId) || chainId <= 0) {
         console.error("Error: invalid chain-id (use e.g. 84532 for Base Sepolia, 8453 for Base mainnet)");
         process.exit(1);
@@ -77,5 +84,22 @@ async function main() {
         console.error("Error:", err instanceof Error ? err.message : String(err));
         process.exit(1);
     }
+});
+async function main() {
+    let argv = process.argv.slice(2);
+    if (argv.length === 0) {
+        argv = ["sync"];
+    }
+    const first = argv[0];
+    if (first &&
+        !first.startsWith("-") &&
+        first !== "sync" &&
+        first !== "-h" &&
+        first !== "--help" &&
+        first !== "-V" &&
+        first !== "--version") {
+        argv = ["sync", ...argv];
+    }
+    await program.parseAsync(argv, { from: "user" });
 }
 main();

package/dist/fleet-alerts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fleet-alerts.d.ts","sourceRoot":"","sources":["../src/fleet-alerts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAOpC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EAAE,EAC1B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,UAAU,EAAE,CAAC,CAwOvB"}
+{"version":3,"file":"fleet-alerts.d.ts","sourceRoot":"","sources":["../src/fleet-alerts.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAOpC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EAAE,EAC1B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,UAAU,EAAE,CAAC,CAwOvB"}

package/dist/fleet-alerts.js

@@ -2,7 +2,8 @@
  * Fleet alerts — one-shot query for security-relevant events for fleet accounts.
  * Queries graph DB for linked facilities/SLAs, then RPC for on-chain events.
  */
-import { createPublicClient, http, parseAbiItem, isAddress } from "viem";
+import { createPublicClient, parseAbiItem, isAddress } from "viem";
+import { transportFromRpcUrl } from "@economicagents/viem-rpc";
 import { base, baseSepolia } from "viem/chains";
 import { getDatabase } from "./store.js";
 const CHUNK_SIZE = 9999n;
@@ -17,7 +18,7 @@ export async function getFleetAlerts(graphPath, rpcUrl, accountAddresses, option
     if (!rpcUrl || typeof rpcUrl !== "string" || !rpcUrl.trim()) {
         throw new Error("getFleetAlerts requires a non-empty rpcUrl");
     }
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     // 1. Facilities where lender or borrower in fleet accounts
     const facilityAddresses = [];
     if (normalized.length > 0) {
@@ -40,7 +41,7 @@ export async function getFleetAlerts(graphPath, rpcUrl, accountAddresses, option
     const chain = chainId === base.id ? base : baseSepolia;
     const client = createPublicClient({
         chain,
-        transport: http(rpcUrl),
+        transport: transportFromRpcUrl(rpcUrl),
     });
     const toBlock = options?.toBlock ?? Number(await client.getBlockNumber());
     const fromBlock = options?.fromBlock ?? Math.max(0, toBlock - DEFAULT_BLOCK_RANGE);

package/dist/index.d.ts

@@ -8,6 +8,7 @@ export { getPaymentsFrom, getPaymentsTo, getAccountAnalytics, getAccountAnalytic
 export { getFleetAlerts } from "./fleet-alerts.js";
 export { getRecommendations } from "./recommendations.js";
 export type { GraphConfig, SyncResult, PaymentSource, } from "./types.js";
+export type { GraphDatabaseOptions } from "./store.js";
 export type { PaymentRow, AccountAnalytics, CreditScoreResult, PaymentTrend, FleetSummary, } from "./queries.js";
 export type { FleetAlert, GetFleetAlertsOptions } from "./fleet-alerts.js";
 export type { ProviderRecommendation, ProviderInfo } from "./recommendations.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAuBH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK1D,wBAAsB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAokBxE;AAED,OAAO,EACL,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EACV,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwBH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK1D,wBAAsB,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAokBxE;AAED,OAAO,EACL,WAAW,EACX,aAAa,EACb,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,eAAe,EACf,aAAa,EACb,mBAAmB,EACnB,0BAA0B,EAC1B,kBAAkB,EAClB,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,YAAY,EACV,WAAW,EACX,UAAU,EACV,aAAa,GACd,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvD,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACb,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,UAAU,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,YAAY,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,7 +1,8 @@
 /**
  * Economic graph sync - indexes on-chain events to build transaction graph.
  */
-import { createPublicClient, http, parseAbiItem } from "viem";
+import { createPublicClient, parseAbiItem } from "viem";
+import { transportFromRpcUrl } from "@economicagents/viem-rpc";
 import { base, baseSepolia } from "viem/chains";
 import { getDatabase, insertAccount, insertPayment, insertUserOp, insertFacility, insertEscrow, insertSplitter, insertSLA, insertSLAEvent, getSyncState, setSyncState, getAccountAddresses, getFacilityAddresses, getEscrowAddresses, getSplitterAddresses, getSLAAddresses, } from "./store.js";
 const CHUNK_SIZE = 9999n;
@@ -10,7 +11,7 @@ export async function syncGraph(config) {
     const chain = config.chainId === base.id ? base : baseSepolia;
     const client = createPublicClient({
         chain,
-        transport: http(config.rpcUrl),
+        transport: transportFromRpcUrl(config.rpcUrl),
     });
     const db = getDatabase(config.graphPath);
     const result = {

package/dist/queries.js

@@ -16,7 +16,7 @@ export function getBlockRangeForPeriod(graphPath, period) {
     const blocks = BLOCKS_PER_PERIOD[period];
     if (!blocks)
         return null;
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const maxBlock = getMaxBlock(db);
     return { fromBlock: Math.max(0, maxBlock - blocks), toBlock: maxBlock };
 }
@@ -33,7 +33,7 @@ export function getPaymentsTo(db, address) {
     return rows;
 }
 export function getAccountAnalytics(graphPath, address) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const addr = address.toLowerCase();
     const outflows = db
         .prepare("SELECT amount, source FROM payments WHERE fromAddr = ?")
@@ -81,7 +81,7 @@ export function getAccountAnalytics(graphPath, address) {
     };
 }
 export function computeCreditScore(graphPath, address) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const addr = address.toLowerCase();
     const outflows = getPaymentsFrom(db, addr);
     const inflows = getPaymentsTo(db, addr);
@@ -119,7 +119,7 @@ export function computeCreditScore(graphPath, address) {
     };
 }
 export function computeCreditScoreInRange(graphPath, address, fromBlock, toBlock) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const addr = address.toLowerCase();
     const outflows = db
         .prepare("SELECT fromAddr, toAddr, amount, token, blockNumber, source FROM payments WHERE fromAddr = ? AND blockNumber >= ? AND blockNumber <= ? ORDER BY blockNumber")
@@ -162,7 +162,7 @@ export function computeCreditScoreInRange(graphPath, address, fromBlock, toBlock
     };
 }
 export function getAccountAnalyticsInRange(graphPath, address, fromBlock, toBlock) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const addr = address.toLowerCase();
     const outflows = db
         .prepare("SELECT amount, source FROM payments WHERE fromAddr = ? AND blockNumber >= ? AND blockNumber <= ?")
@@ -211,7 +211,7 @@ export function getAccountAnalyticsInRange(graphPath, address, fromBlock, toBloc
 }
 /** Rolling spend/revenue trends. Groups by block bucket (~1 day = 43200 blocks on Base). */
 export function getPaymentTrends(graphPath, address, period) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const addr = address.toLowerCase();
     const maxBlock = getMaxBlock(db);
     const blocks = BLOCKS_PER_PERIOD[period] ?? BLOCKS_PER_PERIOD["30d"];
@@ -252,7 +252,7 @@ export function getPaymentTrends(graphPath, address, period) {
     });
 }
 export function exportPaymentsCsv(graphPath, address, fromBlock, toBlock) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const addr = address.toLowerCase();
     let sql = "SELECT fromAddr, toAddr, amount, token, blockNumber, txHash, source FROM payments WHERE (fromAddr = ? OR toAddr = ?)";
     const args = [addr, addr];
@@ -278,7 +278,7 @@ export function exportPaymentsCsv(graphPath, address, fromBlock, toBlock) {
     return [header, ...lines].join("\n");
 }
 export function getFleetSummary(graphPath, accountAddresses) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const normalized = accountAddresses.map((a) => a.toLowerCase());
     let totalOutflow = 0n;
     let totalInflow = 0n;

package/dist/recommendations.js

@@ -10,7 +10,7 @@ import { getDatabase } from "./store.js";
  * @param providers - Provider list (e.g. from loadProviders(indexPath))
  */
 export function getRecommendations(graphPath, providers, accountAddress, capability, limit = 5) {
-    const db = getDatabase(graphPath);
+    const db = getDatabase(graphPath, { readonly: true });
     const addr = accountAddress.toLowerCase();
     const paymentWalletToProvider = new Map();
     for (const p of providers) {

package/dist/store.d.ts

@@ -33,8 +33,12 @@ export declare function setSqlJsFallback(SQL: {
 export declare function isUsingBetterSqlite3(): boolean;
 /** Exported for tests: whether SQLite (better-sqlite3 or sql.js fallback) is available. */
 export declare function isSqliteAvailable(): boolean;
+export type GraphDatabaseOptions = {
+    /** Use read-only mode (API / analytics). Lets graph sync hold the write lock without SQLITE_BUSY. */
+    readonly?: boolean;
+};
 export declare function ensureGraphDir(graphPath: string): void;
-export declare function getDatabase(graphPath: string): SqliteDb;
+export declare function getDatabase(graphPath: string, options?: GraphDatabaseOptions): SqliteDb;
 export declare function closeDatabase(): void;
 export declare function insertAccount(database: SqliteDb, address: string, owner: string, firstSeenBlock: number): void;
 export declare function insertPayment(database: SqliteDb, fromAddr: string, toAddr: string, amount: string, token: string, blockNumber: number, txHash: string, logIndex: number | null, source: string): void;

package/dist/store.d.ts.map

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

package/dist/store.js

@@ -8,8 +8,12 @@ import { join } from "path";
 const require = createRequire(import.meta.url);
 let db = null;
 let dbPath = null;
+/** Read-only handle (API analytics) — avoids write locks vs graph sync in a second process */
+let roDb = null;
+let roDbPath = null;
 let sqliteAvailable = null;
 let sqlJsFallback = null;
+const GRAPH_SQLITE_BUSY_TIMEOUT_MS = 30_000;
 /** For tests: set sql.js as fallback when better-sqlite3 native bindings are unavailable. */
 export function setSqlJsFallback(SQL) {
     sqlJsFallback = SQL;
@@ -74,14 +78,29 @@ export function isSqliteAvailable() {
         return true;
     return sqlJsFallback !== null;
 }
-function getDb(graphPath) {
+function getDb(graphPath, options) {
+    const wantsReadonly = options?.readonly === true;
+    /** sql.js tests use one in-memory DB; read-only file semantics do not apply */
+    isSqliteAvailable();
+    const readonly = wantsReadonly && sqliteAvailable === true && sqlJsFallback === null;
     const resolvedPath = join(graphPath, "graph.db");
-    if (db && dbPath === resolvedPath)
-        return db;
-    if (db) {
-        db.close();
-        db = null;
-        dbPath = null;
+    if (readonly) {
+        if (roDb && roDbPath === resolvedPath)
+            return roDb;
+        if (roDb) {
+            roDb.close();
+            roDb = null;
+            roDbPath = null;
+        }
+    }
+    else {
+        if (db && dbPath === resolvedPath)
+            return db;
+        if (db) {
+            db.close();
+            db = null;
+            dbPath = null;
+        }
     }
     if (!isSqliteAvailable()) {
         throw new Error("better-sqlite3 or sql.js required for graph. Install: npm install better-sqlite3");
@@ -89,8 +108,23 @@ function getDb(graphPath) {
     try {
         if (sqliteAvailable) {
             const Database = require("better-sqlite3");
+            if (readonly) {
+                const nativeDb = new Database(resolvedPath, {
+                    readonly: true,
+                    fileMustExist: true,
+                    timeout: GRAPH_SQLITE_BUSY_TIMEOUT_MS,
+                });
+                roDb = nativeDb;
+                roDbPath = resolvedPath;
+                return nativeDb;
+            }
             mkdirSync(graphPath, { recursive: true });
-            db = new Database(resolvedPath);
+            const nativeDb = new Database(resolvedPath, {
+                timeout: GRAPH_SQLITE_BUSY_TIMEOUT_MS,
+            });
+            nativeDb.pragma("journal_mode = WAL");
+            nativeDb.pragma(`busy_timeout = ${GRAPH_SQLITE_BUSY_TIMEOUT_MS}`);
+            db = nativeDb;
             dbPath = resolvedPath;
         }
         else if (sqlJsFallback) {
@@ -192,8 +226,8 @@ function initSchema(database) {
 export function ensureGraphDir(graphPath) {
     mkdirSync(graphPath, { recursive: true });
 }
-export function getDatabase(graphPath) {
-    return getDb(graphPath);
+export function getDatabase(graphPath, options) {
+    return getDb(graphPath, options);
 }
 export function closeDatabase() {
     if (db) {
@@ -201,6 +235,11 @@ export function closeDatabase() {
         db = null;
         dbPath = null;
     }
+    if (roDb) {
+        roDb.close();
+        roDb = null;
+        roDbPath = null;
+    }
 }
 export function insertAccount(database, address, owner, firstSeenBlock) {
     database

package/dist/viem-transport.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Matches @economicagents/sdk/viem-transport — duplicated here to avoid sdk↔graph pkg cycle.
+ */
+import { type Transport } from "viem";
+export declare function transportFromRpcUrl(rpcUrl: string): Transport;
+//# sourceMappingURL=viem-transport.d.ts.map

package/dist/viem-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viem-transport.d.ts","sourceRoot":"","sources":["../src/viem-transport.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,MAAM,CAAC;AAEvD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAO7D"}

package/dist/viem-transport.js

@@ -0,0 +1,12 @@
+/**
+ * Matches @economicagents/sdk/viem-transport — duplicated here to avoid sdk↔graph pkg cycle.
+ */
+import { http, webSocket } from "viem";
+export function transportFromRpcUrl(rpcUrl) {
+    const trimmed = rpcUrl.trim();
+    const lower = trimmed.toLowerCase();
+    if (lower.startsWith("wss://") || lower.startsWith("ws://")) {
+        return webSocket(trimmed);
+    }
+    return http(trimmed);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@economicagents/graph",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Economic graph for AEP - transaction graph, payments, credit events, credit scoring, recommendations",
   "license": "Apache-2.0",
   "repository": {
@@ -32,7 +32,9 @@
     "aep-graph": "./dist/cli.js"
   },
   "dependencies": {
-    "viem": "^2.21.0"
+    "commander": "^12.1.0",
+    "viem": "^2.47.5",
+    "@economicagents/viem-rpc": "0.2.0"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.1.0"