@oobe-protocol-labs/synapse-sap-sdk 0.1.0

package/dist/esm/postgres/adapter.js

@@ -0,0 +1,678 @@
+/**
+ * @module postgres/adapter
+ * @description PostgreSQL adapter for SAP v2 — syncs on-chain accounts
+ * to a relational database for off-chain querying and analytics.
+ *
+ * The adapter uses `pg` (node-postgres) as the database driver.
+ * It is database-driver agnostic at the interface level — you can
+ * substitute any client that implements the `PgClient` interface.
+ *
+ * @category Postgres
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapPostgres } from "@synapse-sap/sdk/postgres";
+ * import { Pool } from "pg";
+ *
+ * const pool = new Pool({ connectionString: "postgresql://..." });
+ * const pg = new SapPostgres(pool, sapClient);
+ *
+ * // Run schema migration
+ * await pg.migrate();
+ *
+ * // Sync all agents to PostgreSQL
+ * await pg.syncAgents();
+ *
+ * // Full sync (all account types)
+ * await pg.syncAll();
+ *
+ * // Query off-chain
+ * const agents = await pg.query("SELECT * FROM sap_agents WHERE is_active = true");
+ * ```
+ */
+import { serializeGlobalRegistry, serializeAgent, serializeAgentStats, serializeFeedback, serializeCapabilityIndex, serializeProtocolIndex, serializeVault, serializeSession, serializeEpochPage, serializeDelegate, serializeTool, serializeCheckpoint, serializeEscrow, serializeToolCategoryIndex, serializeAttestation, serializeLedger, serializeLedgerPage, } from "./serializers";
+import { deriveGlobalRegistry } from "../pda";
+import * as fs from "fs";
+import * as path from "path";
+// ═══════════════════════════════════════════════════════════════════
+//  SapPostgres Adapter
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * @name SapPostgres
+ * @description PostgreSQL off-chain mirror for SAP v2 on-chain data.
+ *
+ * Connects to a PostgreSQL database and synchronizes all 22 on-chain
+ * account types into relational tables. Supports incremental sync,
+ * event logging, and cursor-based pagination.
+ *
+ * @category Postgres
+ * @since v0.1.0
+ *
+ * @example
+ * ```ts
+ * import { SapPostgres } from "@synapse-sap/sdk/postgres";
+ * import { Pool } from "pg";
+ * import { SapClient } from "@synapse-sap/sdk";
+ *
+ * const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+ * const sap = SapClient.from(provider);
+ * const pg = new SapPostgres(pool, sap);
+ *
+ * await pg.migrate();        // Create tables
+ * await pg.syncAll();         // Mirror on-chain state
+ *
+ * // Read from PostgreSQL
+ * const { rows } = await pg.query(
+ *   "SELECT * FROM sap_agents WHERE is_active = true ORDER BY reputation_score DESC"
+ * );
+ * ```
+ */
+export class SapPostgres {
+    db;
+    client;
+    debug;
+    constructor(db, client, debug = false) {
+        this.db = db;
+        this.client = client;
+        this.debug = debug;
+    }
+    // ═════════════════════════════════════════════
+    //  Schema Migration
+    // ═════════════════════════════════════════════
+    /**
+     * @name migrate
+     * @description Run the SQL schema migration to create all SAP tables,
+     * indexes, views, and enum types. Safe to call multiple times
+     * (uses `CREATE IF NOT EXISTS`).
+     * @returns {Promise<void>}
+     * @since v0.1.0
+     */
+    async migrate() {
+        const schemaPath = path.join(__dirname, "schema.sql");
+        const sql = fs.readFileSync(schemaPath, "utf-8");
+        await this.db.query(sql);
+        this.log("Schema migration complete");
+    }
+    /**
+     * @name migrateWithSQL
+     * @description Run migration with a custom SQL string.
+     * Useful when the schema.sql file is bundled differently.
+     * @param sql - The full SQL schema to execute.
+     * @since v0.1.0
+     */
+    async migrateWithSQL(sql) {
+        await this.db.query(sql);
+        this.log("Schema migration complete (custom SQL)");
+    }
+    // ═════════════════════════════════════════════
+    //  Raw Query
+    // ═════════════════════════════════════════════
+    /**
+     * @name query
+     * @description Execute a raw SQL query against the database.
+     * @param text - SQL query string.
+     * @param values - Parameterized values.
+     * @returns Query result with rows and rowCount.
+     * @since v0.1.0
+     */
+    async query(text, values) {
+        this.log(`QUERY: ${text.substring(0, 120)}...`);
+        return this.db.query(text, values);
+    }
+    // ═════════════════════════════════════════════
+    //  Upsert Helper
+    // ═════════════════════════════════════════════
+    /**
+     * @name upsert
+     * @description Insert or update a row in the specified table.
+     * Uses `ON CONFLICT (pda) DO UPDATE` for idempotent writes.
+     * @param table - Target table name.
+     * @param row - Key-value record to insert.
+     * @since v0.1.0
+     */
+    async upsert(table, row) {
+        const keys = Object.keys(row);
+        const values = Object.values(row);
+        const placeholders = keys.map((_, i) => `$${i + 1}`);
+        const updates = keys
+            .filter((k) => k !== "pda")
+            .map((k) => `${k} = $${keys.indexOf(k) + 1}`)
+            .join(", ");
+        const sql = `
+      INSERT INTO ${table} (${keys.join(", ")})
+      VALUES (${placeholders.join(", ")})
+      ON CONFLICT (pda) DO UPDATE SET ${updates}
+    `;
+        await this.db.query(sql, values);
+    }
+    /**
+     * @name upsertBatch
+     * @description Upsert multiple rows in a single transaction.
+     * @param table - Target table name.
+     * @param rows - Array of key-value records.
+     * @since v0.1.0
+     */
+    async upsertBatch(table, rows) {
+        if (rows.length === 0)
+            return;
+        await this.db.query("BEGIN");
+        try {
+            for (const row of rows) {
+                await this.upsert(table, row);
+            }
+            await this.db.query("COMMIT");
+        }
+        catch (err) {
+            await this.db.query("ROLLBACK");
+            throw err;
+        }
+    }
+    // ═════════════════════════════════════════════
+    //  Sync Cursors
+    // ═════════════════════════════════════════════
+    /**
+     * @name getCursor
+     * @description Get the sync cursor for a given account type.
+     * @param accountType - The account type to check.
+     * @since v0.1.0
+     */
+    async getCursor(accountType) {
+        const { rows } = await this.db.query("SELECT * FROM sap_sync_cursors WHERE account_type = $1", [accountType]);
+        return rows[0] ?? null;
+    }
+    /**
+     * @name updateCursor
+     * @description Update the sync cursor after a successful sync.
+     * @param accountType - The account type synced.
+     * @param slot - The last synced slot.
+     * @param signature - Optional last TX signature.
+     * @since v0.1.0
+     */
+    async updateCursor(accountType, slot, signature) {
+        await this.db.query(`UPDATE sap_sync_cursors
+       SET last_slot = $1, last_signature = $2, updated_at = NOW()
+       WHERE account_type = $3`, [slot, signature ?? null, accountType]);
+    }
+    // ═════════════════════════════════════════════
+    //  Individual Sync Methods
+    // ═════════════════════════════════════════════
+    /**
+     * @name syncGlobal
+     * @description Sync the GlobalRegistry singleton to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncGlobal() {
+        const [globalPda] = deriveGlobalRegistry();
+        const pdaStr = globalPda.toBase58();
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const data = await this.client.program.account.globalRegistry.fetch(globalPda);
+            const slot = await this.client.program.provider.connection.getSlot();
+            const row = serializeGlobalRegistry(pdaStr, data, slot);
+            await this.upsert("sap_global_registry", row);
+            await this.updateCursor("global_registry", slot);
+            this.log(`Synced global registry`);
+        }
+        catch {
+            this.log("Global registry not found (not initialized yet)");
+        }
+    }
+    /**
+     * @name syncAgents
+     * @description Sync all AgentAccount PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncAgents() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.agentAccount.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeAgent(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_agents", rows);
+        await this.updateCursor("agents", slot);
+        this.log(`Synced ${rows.length} agents`);
+        return rows.length;
+    }
+    /**
+     * @name syncAgentStats
+     * @description Sync all AgentStats PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncAgentStats() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.agentStats.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeAgentStats(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_agent_stats", rows);
+        await this.updateCursor("agent_stats", slot);
+        this.log(`Synced ${rows.length} agent stats`);
+        return rows.length;
+    }
+    /**
+     * @name syncFeedbacks
+     * @description Sync all FeedbackAccount PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncFeedbacks() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.feedbackAccount.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeFeedback(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_feedbacks", rows);
+        await this.updateCursor("feedbacks", slot);
+        this.log(`Synced ${rows.length} feedbacks`);
+        return rows.length;
+    }
+    /**
+     * @name syncTools
+     * @description Sync all ToolDescriptor PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncTools() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.toolDescriptor.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeTool(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_tools", rows);
+        await this.updateCursor("tools", slot);
+        this.log(`Synced ${rows.length} tools`);
+        return rows.length;
+    }
+    /**
+     * @name syncEscrows
+     * @description Sync all EscrowAccount PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncEscrows() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.escrowAccount.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeEscrow(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_escrows", rows);
+        await this.updateCursor("escrows", slot);
+        this.log(`Synced ${rows.length} escrows`);
+        return rows.length;
+    }
+    /**
+     * @name syncAttestations
+     * @description Sync all AgentAttestation PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncAttestations() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.agentAttestation.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeAttestation(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_attestations", rows);
+        await this.updateCursor("attestations", slot);
+        this.log(`Synced ${rows.length} attestations`);
+        return rows.length;
+    }
+    /**
+     * @name syncVaults
+     * @description Sync all MemoryVault PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncVaults() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.memoryVault.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeVault(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_memory_vaults", rows);
+        await this.updateCursor("memory_vaults", slot);
+        this.log(`Synced ${rows.length} vaults`);
+        return rows.length;
+    }
+    /**
+     * @name syncSessions
+     * @description Sync all SessionLedger PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncSessions() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.sessionLedger.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeSession(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_sessions", rows);
+        await this.updateCursor("sessions", slot);
+        this.log(`Synced ${rows.length} sessions`);
+        return rows.length;
+    }
+    /**
+     * @name syncLedgers
+     * @description Sync all MemoryLedger PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncLedgers() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.memoryLedger.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeLedger(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_memory_ledgers", rows);
+        await this.updateCursor("memory_ledgers", slot);
+        this.log(`Synced ${rows.length} ledgers`);
+        return rows.length;
+    }
+    /**
+     * @name syncLedgerPages
+     * @description Sync all LedgerPage PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncLedgerPages() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.ledgerPage.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeLedgerPage(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_ledger_pages", rows);
+        await this.updateCursor("ledger_pages", slot);
+        this.log(`Synced ${rows.length} ledger pages`);
+        return rows.length;
+    }
+    /**
+     * @name syncCapabilityIndexes
+     * @description Sync all CapabilityIndex PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncCapabilityIndexes() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.capabilityIndex.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeCapabilityIndex(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_capability_indexes", rows);
+        await this.updateCursor("capability_indexes", slot);
+        this.log(`Synced ${rows.length} capability indexes`);
+        return rows.length;
+    }
+    /**
+     * @name syncProtocolIndexes
+     * @description Sync all ProtocolIndex PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncProtocolIndexes() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.protocolIndex.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeProtocolIndex(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_protocol_indexes", rows);
+        await this.updateCursor("protocol_indexes", slot);
+        this.log(`Synced ${rows.length} protocol indexes`);
+        return rows.length;
+    }
+    /**
+     * @name syncToolCategoryIndexes
+     * @description Sync all ToolCategoryIndex PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncToolCategoryIndexes() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.toolCategoryIndex.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeToolCategoryIndex(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_tool_category_indexes", rows);
+        await this.updateCursor("tool_category_indexes", slot);
+        this.log(`Synced ${rows.length} tool category indexes`);
+        return rows.length;
+    }
+    /**
+     * @name syncEpochPages
+     * @description Sync all EpochPage PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncEpochPages() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.epochPage.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeEpochPage(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_epoch_pages", rows);
+        await this.updateCursor("epoch_pages", slot);
+        this.log(`Synced ${rows.length} epoch pages`);
+        return rows.length;
+    }
+    /**
+     * @name syncDelegates
+     * @description Sync all VaultDelegate PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncDelegates() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.vaultDelegate.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeDelegate(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_vault_delegates", rows);
+        await this.updateCursor("vault_delegates", slot);
+        this.log(`Synced ${rows.length} delegates`);
+        return rows.length;
+    }
+    /**
+     * @name syncCheckpoints
+     * @description Sync all SessionCheckpoint PDAs to PostgreSQL.
+     * @since v0.1.0
+     */
+    async syncCheckpoints() {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const accounts = await this.client.program.account.sessionCheckpoint.all();
+        const slot = await this.client.program.provider.connection.getSlot();
+        const rows = accounts.map((a) => serializeCheckpoint(a.publicKey.toBase58(), a.account, slot));
+        await this.upsertBatch("sap_checkpoints", rows);
+        await this.updateCursor("checkpoints", slot);
+        this.log(`Synced ${rows.length} checkpoints`);
+        return rows.length;
+    }
+    // ═════════════════════════════════════════════
+    //  Full Sync
+    // ═════════════════════════════════════════════
+    /**
+     * @name syncAll
+     * @description Sync all on-chain account types to PostgreSQL.
+     *
+     * Fetches every account via `program.account.*.all()` and
+     * upserts into the corresponding table. Reports progress
+     * via the `onProgress` callback.
+     *
+     * @param options - Optional sync configuration.
+     * @returns Summary of synced account counts.
+     * @since v0.1.0
+     *
+     * @example
+     * ```ts
+     * const result = await pg.syncAll({
+     *   onProgress: (synced, total, type) => {
+     *     console.log(`[${type}] ${synced}/${total}`);
+     *   },
+     * });
+     * console.log("Total synced:", result.totalRecords);
+     * ```
+     */
+    async syncAll(options) {
+        const result = {
+            agents: 0,
+            agentStats: 0,
+            feedbacks: 0,
+            tools: 0,
+            escrows: 0,
+            attestations: 0,
+            vaults: 0,
+            sessions: 0,
+            epochPages: 0,
+            delegates: 0,
+            checkpoints: 0,
+            ledgers: 0,
+            ledgerPages: 0,
+            capabilityIndexes: 0,
+            protocolIndexes: 0,
+            toolCategoryIndexes: 0,
+            totalRecords: 0,
+            durationMs: 0,
+        };
+        const start = Date.now();
+        const total = 16;
+        const onProgress = options?.onProgress;
+        // Sync in dependency order
+        await this.syncGlobal();
+        if (onProgress)
+            onProgress(1, total, "global_registry");
+        result.agents = await this.syncAgents();
+        if (onProgress)
+            onProgress(2, total, "agents");
+        result.agentStats = await this.syncAgentStats();
+        if (onProgress)
+            onProgress(3, total, "agent_stats");
+        result.feedbacks = await this.syncFeedbacks();
+        if (onProgress)
+            onProgress(4, total, "feedbacks");
+        result.tools = await this.syncTools();
+        if (onProgress)
+            onProgress(5, total, "tools");
+        result.escrows = await this.syncEscrows();
+        if (onProgress)
+            onProgress(6, total, "escrows");
+        result.attestations = await this.syncAttestations();
+        if (onProgress)
+            onProgress(7, total, "attestations");
+        result.vaults = await this.syncVaults();
+        if (onProgress)
+            onProgress(8, total, "vaults");
+        result.sessions = await this.syncSessions();
+        if (onProgress)
+            onProgress(9, total, "sessions");
+        result.epochPages = await this.syncEpochPages();
+        if (onProgress)
+            onProgress(10, total, "epoch_pages");
+        result.delegates = await this.syncDelegates();
+        if (onProgress)
+            onProgress(11, total, "delegates");
+        result.checkpoints = await this.syncCheckpoints();
+        if (onProgress)
+            onProgress(12, total, "checkpoints");
+        result.ledgers = await this.syncLedgers();
+        if (onProgress)
+            onProgress(13, total, "ledgers");
+        result.ledgerPages = await this.syncLedgerPages();
+        if (onProgress)
+            onProgress(14, total, "ledger_pages");
+        result.capabilityIndexes = await this.syncCapabilityIndexes();
+        if (onProgress)
+            onProgress(15, total, "capability_indexes");
+        result.protocolIndexes = await this.syncProtocolIndexes();
+        result.toolCategoryIndexes = await this.syncToolCategoryIndexes();
+        if (onProgress)
+            onProgress(16, total, "indexes");
+        result.totalRecords =
+            result.agents +
+                result.agentStats +
+                result.feedbacks +
+                result.tools +
+                result.escrows +
+                result.attestations +
+                result.vaults +
+                result.sessions +
+                result.epochPages +
+                result.delegates +
+                result.checkpoints +
+                result.ledgers +
+                result.ledgerPages +
+                result.capabilityIndexes +
+                result.protocolIndexes +
+                result.toolCategoryIndexes;
+        result.durationMs = Date.now() - start;
+        this.log(`Full sync complete: ${result.totalRecords} records in ${result.durationMs}ms`);
+        return result;
+    }
+    // ═════════════════════════════════════════════
+    //  Event Sync
+    // ═════════════════════════════════════════════
+    /**
+     * @name syncEvent
+     * @description Store a parsed SAP event in the events log table.
+     * @param eventName - The event name (e.g. "RegisteredEvent").
+     * @param txSignature - The transaction signature.
+     * @param slot - The Solana slot.
+     * @param data - The parsed event data.
+     * @param agentPda - Optional agent PDA for indexing.
+     * @param wallet - Optional wallet for indexing.
+     * @since v0.1.0
+     */
+    async syncEvent(eventName, txSignature, slot, data, agentPda, wallet) {
+        await this.db.query(`INSERT INTO sap_events (event_name, tx_signature, slot, data, agent_pda, wallet)
+       VALUES ($1, $2, $3, $4, $5, $6)`, [eventName, txSignature, slot, JSON.stringify(data), agentPda ?? null, wallet ?? null]);
+    }
+    // ═════════════════════════════════════════════
+    //  Convenience Queries
+    // ═════════════════════════════════════════════
+    /**
+     * @name getAgent
+     * @description Fetch a single agent by PDA or wallet.
+     * @param pdaOrWallet - Agent PDA (base58) or owner wallet.
+     * @since v0.1.0
+     */
+    async getAgent(pdaOrWallet) {
+        const { rows } = await this.db.query("SELECT * FROM sap_agents WHERE pda = $1 OR wallet = $1 LIMIT 1", [pdaOrWallet]);
+        return rows[0] ?? null;
+    }
+    /**
+     * @name getActiveAgents
+     * @description Fetch all active agents, ordered by reputation.
+     * @param limit - Max agents to return (default: 100).
+     * @since v0.1.0
+     */
+    async getActiveAgents(limit = 100) {
+        const { rows } = await this.db.query(`SELECT * FROM sap_active_agents
+       ORDER BY reputation_score DESC
+       LIMIT $1`, [limit]);
+        return rows;
+    }
+    /**
+     * @name getEscrowBalance
+     * @description Fetch escrow balance for a specific agent/depositor pair.
+     * @param agentPda - Agent PDA (base58).
+     * @param depositor - Depositor wallet (base58).
+     * @since v0.1.0
+     */
+    async getEscrowBalance(agentPda, depositor) {
+        const { rows } = await this.db.query("SELECT * FROM sap_escrow_balances WHERE agent = $1 AND depositor = $2", [agentPda, depositor]);
+        return rows[0] ?? null;
+    }
+    /**
+     * @name getAgentTools
+     * @description Fetch all active tools for a given agent.
+     * @param agentPda - Agent PDA (base58).
+     * @since v0.1.0
+     */
+    async getAgentTools(agentPda) {
+        const { rows } = await this.db.query("SELECT * FROM sap_agent_tools WHERE agent = $1", [agentPda]);
+        return rows;
+    }
+    /**
+     * @name getRecentEvents
+     * @description Fetch the most recent events.
+     * @param limit - Max events to return (default: 50).
+     * @param eventName - Optional filter by event name.
+     * @since v0.1.0
+     */
+    async getRecentEvents(limit = 50, eventName) {
+        if (eventName) {
+            const { rows } = await this.db.query("SELECT * FROM sap_events WHERE event_name = $1 ORDER BY id DESC LIMIT $2", [eventName, limit]);
+            return rows;
+        }
+        const { rows } = await this.db.query("SELECT * FROM sap_events ORDER BY id DESC LIMIT $1", [limit]);
+        return rows;
+    }
+    /**
+     * @name getSyncStatus
+     * @description Get the sync status for all account types.
+     * @since v0.1.0
+     */
+    async getSyncStatus() {
+        const { rows } = await this.db.query("SELECT * FROM sap_sync_cursors ORDER BY account_type");
+        return rows;
+    }
+    // ═════════════════════════════════════════════
+    //  Internal
+    // ═════════════════════════════════════════════
+    log(msg) {
+        if (this.debug) {
+            console.log(`[SapPostgres] ${msg}`);
+        }
+    }
+}
+//# sourceMappingURL=adapter.js.map