@fairmint/canton-fairmint-sdk 0.0.2

package/dist/clients/postgres-db-api/cantonDbClient.js

@@ -0,0 +1,2703 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CantonDbClient = void 0;
+const pg_1 = require("pg");
+const config_1 = require("../shared/config");
+function assertEqualLengths(arrays, context) {
+    if (arrays.length === 0)
+        return;
+    const expected = arrays[0].length;
+    for (let i = 1; i < arrays.length; i++) {
+        if (arrays[i].length !== expected) {
+            throw new Error(`${context}: array length mismatch (expected ${expected}, got ${arrays[i].length})`);
+        }
+    }
+}
+class CantonDbClient {
+    constructor(network) {
+        // Initialize the shared config which handles environment loading
+        this.config = new config_1.ProviderConfig();
+        // Use provided network or get from environment variable, defaulting to devnet
+        this.network = network;
+        const databaseUrl = this.getCantonTransactionsDatabaseUrl();
+        if (databaseUrl) {
+            // Extract database name from URL for debugging (without exposing credentials)
+            const dbNameMatch = databaseUrl.match(/\/\/([^:]+:[^@]+@)?[^\/]+\/([^?]+)/);
+            const _dbName = dbNameMatch ? dbNameMatch[2] : 'unknown';
+        }
+        if (!databaseUrl) {
+            throw new Error(`Canton transactions database URL for ${this.network} is not configured. Please set CANTON_TRANSACTIONS_DB_URL_${this.network.toUpperCase()} environment variable.`);
+        }
+        this.pool = new pg_1.Pool({
+            connectionString: databaseUrl,
+            ssl: { rejectUnauthorized: false },
+        });
+        // Test the connection
+        this.pool.on('error', err => {
+            console.error('Unexpected error on idle client', err);
+            process.exit(-1);
+        });
+    }
+    getCantonTransactionsDatabaseUrl() {
+        return this.config.getCantonTransactionsDatabaseUrl(this.network);
+    }
+    getNetwork() {
+        return this.network;
+    }
+    async connect() {
+        return this.pool.connect();
+    }
+    async close() {
+        await this.pool.end();
+    }
+    // Transaction helper - runs a callback within a database transaction
+    // Includes deadlock handling with retry logic and lock timeout
+    async runInTransaction(callback) {
+        const MAX_RETRIES = 5;
+        const LOCK_TIMEOUT_MS = 30000; // 30 seconds
+        const INITIAL_BACKOFF_MS = 100; // Start with 100ms
+        let lastError;
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            const client = await this.pool.connect();
+            try {
+                // Set lock timeout to prevent indefinite waiting
+                await client.query(`SET LOCAL lock_timeout = '${LOCK_TIMEOUT_MS}ms'`);
+                await client.query('BEGIN');
+                const result = await callback(client);
+                await client.query('COMMIT');
+                client.release();
+                return result;
+            }
+            catch (error) {
+                try {
+                    await client.query('ROLLBACK');
+                }
+                catch {
+                    // Ignore rollback errors, we're already in error handling
+                }
+                client.release();
+                // Check if this is a deadlock error (PostgreSQL error code 40P01)
+                // pg library exposes error code in error.code property
+                const pgError = error;
+                const isDeadlock = pgError.code === '40P01' ||
+                    (pgError.message &&
+                        (pgError.message.includes('deadlock detected') ||
+                            pgError.message.toLowerCase().includes('deadlock')));
+                // Check if this is a lock timeout error
+                const isLockTimeout = pgError.message &&
+                    (pgError.message.includes('lock_timeout') ||
+                        pgError.message.includes('canceling statement due to lock timeout') ||
+                        (pgError.message.includes('timeout') &&
+                            pgError.message.includes('lock')));
+                if ((isDeadlock || isLockTimeout) && attempt < MAX_RETRIES - 1) {
+                    // Exponential backoff with jitter
+                    const backoffMs = INITIAL_BACKOFF_MS * 2 ** attempt + Math.random() * 100;
+                    const errorType = isDeadlock ? 'deadlock' : 'lock timeout';
+                    console.warn(`⚠️  Database ${errorType} detected (attempt ${attempt + 1}/${MAX_RETRIES}). ` +
+                        `Retrying after ${Math.round(backoffMs)}ms...`);
+                    await new Promise(resolve => setTimeout(resolve, backoffMs));
+                    lastError = error;
+                    continue;
+                }
+                // Not a retryable error, or max retries reached
+                throw error;
+            }
+        }
+        // This should never be reached, but TypeScript needs it
+        if (lastError instanceof Error) {
+            throw lastError;
+        }
+        throw new Error('Transaction failed after maximum retries');
+    }
+    // Canton Transactions CRUD operations
+    async insertCantonTransaction(tx, client = this.pool) {
+        const query = `
+      INSERT INTO transactions (
+        network, update_id, command_id, workflow_id, effective_at, record_time,
+        external_transaction_hash
+      ) VALUES ($1, $2, $3, $4, $5, $6, $7)
+      ON CONFLICT (network, update_id) DO NOTHING
+      RETURNING id
+    `;
+        const values = [
+            tx.network,
+            tx.update_id,
+            tx.command_id,
+            tx.workflow_id,
+            tx.effective_at,
+            tx.record_time,
+            tx.external_transaction_hash,
+        ];
+        const result = await client.query(query, values);
+        if (result.rows.length === 0) {
+            // Conflict occurred, fetch existing
+            const existingResult = await client.query('SELECT id FROM transactions WHERE network = $1 AND update_id = $2', [tx.network, tx.update_id]);
+            return { id: BigInt(existingResult.rows[0].id) };
+        }
+        return { id: BigInt(result.rows[0].id) };
+    }
+    async insertCantonTransactionProvider(provider, client = this.pool) {
+        const query = `
+      INSERT INTO transaction_providers (
+        transaction_id, provider_id, ledger_offset
+      ) VALUES ($1, $2, $3)
+      ON CONFLICT (transaction_id, provider_id) DO UPDATE
+        SET ledger_offset = EXCLUDED.ledger_offset
+      RETURNING id
+    `;
+        const values = [
+            provider.transaction_id.toString(),
+            provider.provider_id.toString(),
+            provider.ledger_offset.toString(),
+        ];
+        const result = await client.query(query, values);
+        return { id: BigInt(result.rows[0].id) };
+    }
+    async insertCantonTransactionEvent(event, client = this.pool) {
+        const query = `
+      INSERT INTO transaction_events (
+        transaction_id, kind,
+        contract_id, package_id
+      ) VALUES ($1, $2, $3, $4)
+      ON CONFLICT (transaction_id, kind, contract_id, package_id) DO UPDATE SET
+        transaction_id = EXCLUDED.transaction_id
+      RETURNING id
+    `;
+        const values = [
+            event.transaction_id.toString(),
+            event.kind,
+            event.contract_id.toString(),
+            event.package_id.toString(),
+        ];
+        const result = await client.query(query, values);
+        return { id: BigInt(result.rows[0].id) };
+    }
+    async insertCantonTransactionEventProvider(provider, client = this.pool) {
+        const query = `
+      INSERT INTO transaction_event_providers (
+        event_id, provider_id, node_id
+      ) VALUES ($1, $2, $3)
+      ON CONFLICT (event_id, provider_id, node_id) DO NOTHING
+    `;
+        const values = [
+            provider.event_id.toString(),
+            provider.provider_id.toString(),
+            provider.node_id.toString(),
+        ];
+        await client.query(query, values);
+    }
+    // Created event payload now stored on contracts.create_argument; this method is deprecated.
+    async insertCantonTransactionEventCreated() {
+        throw new Error('insertCantonTransactionEventCreated is deprecated; use contracts.create_argument instead.');
+    }
+    async insertCantonTransactionEventExercised(details, client = this.pool) {
+        const query = `
+      INSERT INTO transaction_events_exercised (
+        event_id, interface_id, choice_id, choice_argument,
+        exercise_result
+      ) VALUES ($1, $2, $3, $4, $5)
+      ON CONFLICT (event_id) DO NOTHING
+    `;
+        const values = [
+            details.event_id.toString(),
+            details.interface_id,
+            details.choice_id.toString(),
+            JSON.stringify(details.choice_argument),
+            JSON.stringify(details.exercise_result),
+        ];
+        await client.query(query, values);
+    }
+    async insertCantonTransactionEventExercisedProvider(details, client = this.pool) {
+        const query = `
+      INSERT INTO transaction_events_exercised_providers (
+        event_id, provider_id, node_id, last_descendant_node_id
+      ) VALUES ($1, $2, $3, $4)
+      ON CONFLICT (event_id, provider_id, node_id) DO NOTHING
+    `;
+        const values = [
+            details.event_id.toString(),
+            details.provider_id.toString(),
+            details.node_id.toString(),
+            details.last_descendant_node_id.toString(),
+        ];
+        await client.query(query, values);
+    }
+    async insertCantonTransactionEventAssigned(_details, _client = this.pool) {
+        // Note: Assigned/Unassigned tables are not in V2 schema anymore, but keeping method if caller exists?
+        // If not used, we should remove. User said "update dependencies".
+        // I will leave them failing or remove? The V2 schema dropped them.
+        // I'll comment out or throw for now if I removed the tables.
+        // Actually, I removed them in the SQL script. So these queries will fail.
+        // I should probably remove these methods or make them throw.
+        throw new Error('insertCantonTransactionEventAssigned is deprecated in V2 schema.');
+    }
+    async insertCantonTransactionEventUnassigned(_details, _client = this.pool) {
+        throw new Error('insertCantonTransactionEventUnassigned is deprecated in V2 schema.');
+    }
+    // Junction table methods for party relationships
+    async upsertCantonParty(partyId, network, client = this.pool) {
+        const query = `
+      INSERT INTO parties (network, party_id)
+      VALUES ($1, $2)
+      ON CONFLICT (network, party_id) DO NOTHING
+      RETURNING id
+    `;
+        const result = await client.query(query, [network, partyId]);
+        if (result.rows.length === 0) {
+            // Conflict occurred, fetch existing
+            const existingResult = await client.query('SELECT id FROM parties WHERE network = $1 AND party_id = $2', [network, partyId]);
+            return BigInt(existingResult.rows[0].id);
+        }
+        return BigInt(result.rows[0].id);
+    }
+    async insertActors(contractId, partyIds, actorType, network, client = this.pool) {
+        if (partyIds.length === 0)
+            return;
+        for (const partyId of partyIds) {
+            const partyDbId = await this.upsertCantonParty(partyId, network, client);
+            // Signatory should override observer on conflict; observer should not downgrade signatory
+            const query = actorType === 'signatory'
+                ? `INSERT INTO contract_actors (contract_id, party_id, actor_type)
+             VALUES ($1, $2, 'signatory')
+             ON CONFLICT (contract_id, party_id) DO UPDATE SET actor_type = 'signatory'`
+                : `INSERT INTO contract_actors (contract_id, party_id, actor_type)
+             VALUES ($1, $2, 'observer')
+             ON CONFLICT (contract_id, party_id) DO NOTHING`;
+            await client.query(query, [contractId.toString(), partyDbId.toString()]);
+        }
+    }
+    async insertActingParties(eventId, partyIds, network, client = this.pool) {
+        if (partyIds.length === 0)
+            return;
+        for (const partyId of partyIds) {
+            const partyDbId = await this.upsertCantonParty(partyId, network, client);
+            await client.query(`INSERT INTO transaction_events_exercised_acting_parties
+         (event_id, party_id)
+         VALUES ($1, $2)
+         ON CONFLICT (event_id, party_id) DO NOTHING`, [eventId.toString(), partyDbId.toString()]);
+        }
+    }
+    // Bulk insert methods for improved performance
+    async bulkInsertCantonTransactions(transactions, client = this.pool) {
+        if (transactions.length === 0) {
+            return new Map();
+        }
+        const networks = [];
+        const updateIds = [];
+        const commandIds = [];
+        const workflowIds = [];
+        const effectiveAts = [];
+        const recordTimes = [];
+        const extHashes = [];
+        for (const tx of transactions) {
+            if (!tx.network) {
+                throw new Error(`Transaction missing network: ${JSON.stringify(tx)}`);
+            }
+            if (!tx.update_id) {
+                throw new Error(`Transaction missing update_id: ${JSON.stringify(tx)}`);
+            }
+            networks.push(tx.network);
+            updateIds.push(tx.update_id);
+            commandIds.push(tx.command_id ?? null);
+            workflowIds.push(tx.workflow_id ?? null);
+            effectiveAts.push(tx.effective_at);
+            recordTimes.push(tx.record_time);
+            extHashes.push(tx.external_transaction_hash ?? null);
+        }
+        assertEqualLengths([
+            networks,
+            updateIds,
+            commandIds,
+            workflowIds,
+            effectiveAts,
+            recordTimes,
+            extHashes,
+        ], 'bulkInsertCantonTransactions');
+        const query = `
+      WITH data AS (
+        SELECT
+          unnest($1::text[]) AS network,
+          unnest($2::text[]) AS update_id,
+          unnest($3::text[]) AS command_id,
+          unnest($4::text[]) AS workflow_id,
+          unnest($5::timestamptz[]) AS effective_at,
+          unnest($6::timestamptz[]) AS record_time,
+          unnest($7::text[]) AS external_transaction_hash
+      )
+      INSERT INTO transactions (
+        network, update_id, command_id, workflow_id, effective_at, record_time,
+        external_transaction_hash
+      )
+      SELECT
+        network, update_id, command_id, workflow_id, effective_at, record_time, external_transaction_hash
+      FROM data
+      ON CONFLICT (network, update_id) DO UPDATE SET
+        command_id = EXCLUDED.command_id,
+        workflow_id = EXCLUDED.workflow_id,
+        effective_at = EXCLUDED.effective_at,
+        record_time = EXCLUDED.record_time,
+        external_transaction_hash = EXCLUDED.external_transaction_hash
+      RETURNING id, network, update_id
+    `;
+        const result = await client.query(query, [
+            networks,
+            updateIds,
+            commandIds,
+            workflowIds,
+            effectiveAts,
+            recordTimes,
+            extHashes,
+        ]);
+        const idMap = new Map();
+        for (const row of result.rows) {
+            // Use network + update_id as key to ensure uniqueness across networks
+            const key = `${row.network}:${row.update_id}`;
+            idMap.set(key, BigInt(row.id));
+        }
+        // CRITICAL: With DO UPDATE, all transactions should now be in idMap
+        // Verify we got IDs for all transactions to prevent data loss
+        if (idMap.size !== transactions.length) {
+            throw new Error(`Transaction ID map incomplete: Expected ${transactions.length} transactions, got ${idMap.size} IDs. ` +
+                `This indicates a critical database issue that could result in data loss.`);
+        }
+        return idMap;
+    }
+    async bulkInsertCantonTransactionProviders(providers, client = this.pool) {
+        if (providers.length === 0) {
+            return;
+        }
+        const transactionIds = [];
+        const providerIds = [];
+        const ledgerOffsets = [];
+        for (const provider of providers) {
+            transactionIds.push(provider.transaction_id.toString());
+            providerIds.push(provider.provider_id.toString());
+            ledgerOffsets.push(provider.ledger_offset.toString());
+        }
+        assertEqualLengths([transactionIds, providerIds, ledgerOffsets], 'bulkInsertCantonTransactionProviders');
+        const query = `
+      WITH data AS (
+        SELECT
+          unnest($1::bigint[]) AS transaction_id,
+          unnest($2::bigint[]) AS provider_id,
+          unnest($3::bigint[]) AS ledger_offset
+      )
+      INSERT INTO transaction_providers (
+        transaction_id, provider_id, ledger_offset
+      )
+      SELECT transaction_id, provider_id, ledger_offset
+      FROM data
+      ON CONFLICT (transaction_id, provider_id) DO UPDATE
+        SET ledger_offset = EXCLUDED.ledger_offset
+    `;
+        await client.query(query, [transactionIds, providerIds, ledgerOffsets]);
+    }
+    async bulkInsertCantonTransactionEvents(events, client = this.pool) {
+        if (events.length === 0) {
+            return new Map();
+        }
+        const transactionIds = [];
+        const kinds = [];
+        const contractIds = [];
+        const packageIds = [];
+        for (const event of events) {
+            if (!event.transaction_id) {
+                throw new Error(`Event missing transaction_id: ${JSON.stringify(event)}`);
+            }
+            if (!event.package_id || event.package_id === BigInt(0)) {
+                throw new Error(`Event missing or invalid package_id: ${JSON.stringify(event)}`);
+            }
+            if (!event.contract_id) {
+                throw new Error(`Event missing contract_id: ${JSON.stringify(event)}`);
+            }
+            transactionIds.push(event.transaction_id.toString());
+            kinds.push(event.kind);
+            contractIds.push(event.contract_id.toString());
+            packageIds.push(event.package_id.toString());
+        }
+        assertEqualLengths([transactionIds, kinds, contractIds, packageIds], 'bulkInsertCantonTransactionEvents');
+        const query = `
+      WITH data AS (
+        SELECT
+          unnest($1::bigint[]) AS transaction_id,
+          unnest($2::text[]) AS kind,
+          unnest($3::bigint[]) AS contract_id,
+          unnest($4::bigint[]) AS package_id
+      )
+      INSERT INTO transaction_events (
+        transaction_id, kind,
+        contract_id, package_id
+      )
+      SELECT transaction_id, kind, contract_id, package_id
+      FROM data
+      ON CONFLICT (transaction_id, kind, contract_id, package_id) DO UPDATE SET
+        transaction_id = EXCLUDED.transaction_id
+      RETURNING id, transaction_id, kind, contract_id, package_id
+    `;
+        const result = await client.query(query, [
+            transactionIds,
+            kinds,
+            contractIds,
+            packageIds,
+        ]);
+        const idMap = new Map();
+        for (const row of result.rows) {
+            // Build key from unique constraint fields (must include transaction_id)
+            const key = `${row.transaction_id}-${row.kind}-${row.contract_id}-${row.package_id}`;
+            idMap.set(key, BigInt(row.id));
+        }
+        return idMap;
+    }
+    async bulkInsertCantonTransactionEventProviders(providers, client = this.pool) {
+        if (providers.length === 0) {
+            return;
+        }
+        const eventIds = [];
+        const providerIds = [];
+        const nodeIds = [];
+        for (const provider of providers) {
+            eventIds.push(provider.event_id.toString());
+            providerIds.push(provider.provider_id.toString());
+            nodeIds.push(provider.node_id.toString());
+        }
+        assertEqualLengths([eventIds, providerIds, nodeIds], 'bulkInsertCantonTransactionEventProviders');
+        const query = `
+      WITH data AS (
+        SELECT
+          unnest($1::bigint[]) AS event_id,
+          unnest($2::bigint[]) AS provider_id,
+          unnest($3::bigint[]) AS node_id
+      )
+      INSERT INTO transaction_event_providers (
+        event_id, provider_id, node_id
+      )
+      SELECT event_id, provider_id, node_id
+      FROM data
+      ON CONFLICT (event_id, provider_id, node_id) DO NOTHING
+    `;
+        await client.query(query, [eventIds, providerIds, nodeIds]);
+    }
+    async bulkInsertCantonTransactionEventExercised(details, client = this.pool) {
+        if (details.length === 0) {
+            return;
+        }
+        const eventIds = [];
+        const interfaceIds = [];
+        const choiceIds = [];
+        const choiceArgs = [];
+        const exerciseResults = [];
+        for (const detail of details) {
+            eventIds.push(detail.event_id.toString());
+            interfaceIds.push(detail.interface_id ?? null);
+            choiceIds.push(detail.choice_id.toString());
+            choiceArgs.push(JSON.stringify(detail.choice_argument));
+            exerciseResults.push(JSON.stringify(detail.exercise_result));
+        }
+        assertEqualLengths([eventIds, interfaceIds, choiceIds, choiceArgs, exerciseResults], 'bulkInsertExercised');
+        const query = `
+      WITH data AS (
+        SELECT
+          unnest($1::bigint[]) AS event_id,
+          unnest($2::text[]) AS interface_id,
+          unnest($3::bigint[]) AS choice_id,
+          unnest($4::jsonb[]) AS choice_argument,
+          unnest($5::jsonb[]) AS exercise_result
+      )
+      INSERT INTO transaction_events_exercised (
+        event_id, interface_id, choice_id, choice_argument,
+        exercise_result
+      )
+      SELECT event_id, interface_id, choice_id, choice_argument, exercise_result
+      FROM data
+      ON CONFLICT (event_id) DO UPDATE SET
+        interface_id = EXCLUDED.interface_id,
+        choice_id = EXCLUDED.choice_id,
+        choice_argument = EXCLUDED.choice_argument,
+        exercise_result = EXCLUDED.exercise_result
+    `;
+        await client.query(query, [
+            eventIds,
+            interfaceIds,
+            choiceIds,
+            choiceArgs,
+            exerciseResults,
+        ]);
+    }
+    async bulkInsertCantonTransactionEventExercisedProviders(details, client = this.pool) {
+        if (details.length === 0) {
+            return;
+        }
+        const eventIds = [];
+        const providerIds = [];
+        const nodeIds = [];
+        const lastDescendantIds = [];
+        for (const detail of details) {
+            eventIds.push(detail.event_id.toString());
+            providerIds.push(detail.provider_id.toString());
+            nodeIds.push(detail.node_id.toString());
+            lastDescendantIds.push(detail.last_descendant_node_id.toString());
+        }
+        assertEqualLengths([eventIds, providerIds, nodeIds, lastDescendantIds], 'bulkInsertExercisedProviders');
+        const query = `
+      WITH data AS (
+        SELECT
+          unnest($1::bigint[]) AS event_id,
+          unnest($2::bigint[]) AS provider_id,
+          unnest($3::bigint[]) AS node_id,
+          unnest($4::bigint[]) AS last_descendant_node_id
+      )
+      INSERT INTO transaction_events_exercised_providers (
+        event_id, provider_id, node_id, last_descendant_node_id
+      )
+      SELECT event_id, provider_id, node_id, last_descendant_node_id
+      FROM data
+      ON CONFLICT (event_id, provider_id, node_id) DO NOTHING
+    `;
+        await client.query(query, [
+            eventIds,
+            providerIds,
+            nodeIds,
+            lastDescendantIds,
+        ]);
+    }
+    async getLastProcessedOffset(provider) {
+        let query;
+        let values = [];
+        if (provider) {
+            // Get the provider_id first
+            const providerQuery = `
+        SELECT id FROM providers
+        WHERE network = $1 AND provider = $2
+        LIMIT 1
+      `;
+            const providerResult = await this.pool.query(providerQuery, [
+                this.network,
+                provider,
+            ]);
+            if (providerResult.rows.length === 0) {
+                return BigInt(0);
+            }
+            const providerId = providerResult.rows[0].id;
+            query = `
+        SELECT MAX(ledger_offset) as max_offset
+        FROM transaction_providers
+        WHERE provider_id = $1
+      `;
+            values = [providerId];
+        }
+        else {
+            query = `
+        SELECT MAX(ledger_offset) as max_offset
+        FROM transaction_providers
+      `;
+        }
+        const result = await this.pool.query(query, values);
+        const maxOffset = result.rows[0].max_offset;
+        return maxOffset ? BigInt(maxOffset) : BigInt(0);
+    }
+    async getAllPartiesForNetwork() {
+        const query = `
+      SELECT party_id
+      FROM parties
+      WHERE network = $1
+      ORDER BY party_id
+    `;
+        const result = await this.pool.query(query, [this.network]);
+        return result.rows;
+    }
+    /**
+     * Find all transaction update IDs that involve a specific contract ID Returns transactions ordered by record_time
+     * (most recent first)
+     */
+    async findTransactionsByContractId(contractId) {
+        const query = `
+      SELECT DISTINCT t.update_id, t.record_time, e.kind
+      FROM transaction_events e
+      INNER JOIN transactions t ON e.transaction_id = t.id
+      INNER JOIN contracts c ON e.contract_id = c.id
+      WHERE c.canton_contract_id = $1 AND t.network = $2
+      ORDER BY t.record_time DESC
+    `;
+        const result = await this.pool.query(query, [contractId, this.network]);
+        return result.rows;
+    }
+    /**
+     * Get comprehensive contract history for a specific contract ID Returns Created event, Archive event (if exists), and
+     * all Exercise events with updateIds
+     */
+    async getContractHistory(contractId) {
+        // Created event (uses contracts.create_argument; actors via transaction_event_actors)
+        const createdQuery = `
+      SELECT
+        t.update_id,
+        t.record_time,
+        t.effective_at,
+        c.create_argument,
+        pkg.package_id || ':' || ct.module_name || ':' || ct.template_name as template_id,
+        ct.package_name,
+        COALESCE(
+          json_agg(DISTINCT sp.party_id) FILTER (WHERE sp.party_id IS NOT NULL),
+          '[]'::json
+        ) as signatories,
+        COALESCE(
+          json_agg(DISTINCT op.party_id) FILTER (WHERE op.party_id IS NOT NULL),
+          '[]'::json
+        ) as observers
+      FROM transaction_events e
+      INNER JOIN transactions t ON e.transaction_id = t.id
+      INNER JOIN contracts c ON e.contract_id = c.id
+      INNER JOIN templates ct ON c.template_id = ct.id
+      INNER JOIN packages pkg ON e.package_id = pkg.id
+      LEFT JOIN contract_actors act_sig ON act_sig.contract_id = c.id AND act_sig.actor_type = 'signatory'
+      LEFT JOIN parties sp ON act_sig.party_id = sp.id
+      LEFT JOIN contract_actors act_obs ON act_obs.contract_id = c.id
+      LEFT JOIN parties op ON act_obs.party_id = op.id
+      WHERE c.canton_contract_id = $1
+        AND e.kind = 'created'
+        AND t.network = $2
+      GROUP BY t.update_id, t.record_time, t.effective_at, c.create_argument, pkg.package_id, ct.module_name, ct.template_name, ct.package_name
+      ORDER BY t.record_time ASC
+      LIMIT 1
+    `;
+        // Archive event (if exists)
+        const archivedQuery = `
+      SELECT
+        t.update_id,
+        t.record_time,
+        t.effective_at,
+        pkg.package_id || ':' || ct.module_name || ':' || ct.template_name as template_id,
+        ct.package_name,
+        e.kind as event_kind
+      FROM transaction_events e
+      INNER JOIN transactions t ON e.transaction_id = t.id
+      INNER JOIN contracts c ON e.contract_id = c.id
+      INNER JOIN templates ct ON c.template_id = ct.id
+      INNER JOIN packages pkg ON e.package_id = pkg.id
+      WHERE c.canton_contract_id = $1
+        AND e.kind = 'archived'
+        AND t.network = $2
+      ORDER BY t.record_time ASC
+      LIMIT 1
+    `;
+        // All choice events (consuming and non-consuming)
+        const exercisedQuery = `
+      SELECT
+        t.update_id,
+        t.record_time,
+        t.effective_at,
+        cc.choice,
+        eee.interface_id,
+        e.kind as event_kind,
+        eee.choice_argument,
+        eee.exercise_result,
+        pkg.package_id || ':' || ct.module_name || ':' || ct.template_name as template_id,
+        ct.package_name,
+        COALESCE(
+          json_agg(DISTINCT ap.party_id) FILTER (WHERE ap.party_id IS NOT NULL),
+          '[]'::json
+        ) as acting_parties,
+        (
+          SELECT COUNT(*)
+          FROM transaction_events tx_events
+          WHERE tx_events.transaction_id = t.id
+        ) as event_count,
+        (
+          SELECT COALESCE(
+            json_agg(
+              json_build_object(
+                'templateName', tx_templates.template_name,
+                'packageName', tx_templates.package_name,
+                'kind', tx_counts.kind,
+                'count', tx_counts.count
+              ) ORDER BY tx_templates.package_name, tx_templates.template_name, tx_counts.kind
+            ),
+            '[]'::json
+          )
+          FROM (
+            SELECT
+              tx_c.template_id,
+              tx_events.kind,
+              COUNT(*) as count
+            FROM transaction_events tx_events
+            JOIN contracts tx_c ON tx_events.contract_id = tx_c.id
+            WHERE tx_events.transaction_id = t.id
+            GROUP BY tx_c.template_id, tx_events.kind
+          ) tx_counts
+          INNER JOIN templates tx_templates ON tx_counts.template_id = tx_templates.id
+        ) as event_breakdown
+      FROM transaction_events e
+      INNER JOIN transactions t ON e.transaction_id = t.id
+      INNER JOIN contracts c ON e.contract_id = c.id
+      INNER JOIN templates ct ON c.template_id = ct.id
+      INNER JOIN packages pkg ON e.package_id = pkg.id
+      INNER JOIN transaction_events_exercised eee ON e.id = eee.event_id
+      INNER JOIN choices cc ON eee.choice_id = cc.id
+      LEFT JOIN transaction_events_exercised_acting_parties aep ON eee.event_id = aep.event_id
+      LEFT JOIN parties ap ON aep.party_id = ap.id
+      WHERE c.canton_contract_id = $1
+        AND e.kind IN ('consuming_choice', 'non_consuming_choice')
+        AND t.network = $2
+      GROUP BY t.update_id, t.record_time, t.effective_at, cc.choice, eee.interface_id, eee.choice_argument, eee.exercise_result, pkg.package_id, ct.module_name, ct.template_name, ct.package_name, e.kind, t.id
+      ORDER BY t.record_time DESC
+    `;
+        const [createdResult, archivedResult, exercisedResult] = await Promise.all([
+            this.pool.query(createdQuery, [contractId, this.network]),
+            this.pool.query(archivedQuery, [contractId, this.network]),
+            this.pool.query(exercisedQuery, [contractId, this.network]),
+        ]);
+        const created = createdResult.rows.length > 0
+            ? {
+                updateId: createdResult.rows[0].update_id,
+                recordTime: createdResult.rows[0].record_time,
+                effectiveAt: createdResult.rows[0].effective_at,
+                createArgument: createdResult.rows[0].create_argument,
+                templateId: createdResult.rows[0].template_id,
+                packageName: createdResult.rows[0].package_name,
+                signatories: createdResult.rows[0].signatories ?? [],
+                observers: createdResult.rows[0].observers ?? [],
+            }
+            : null;
+        const archived = archivedResult.rows.length > 0
+            ? {
+                updateId: archivedResult.rows[0].update_id,
+                recordTime: archivedResult.rows[0].record_time,
+                effectiveAt: archivedResult.rows[0].effective_at,
+                eventKind: archivedResult.rows[0].event_kind,
+                templateId: archivedResult.rows[0].template_id,
+                packageName: archivedResult.rows[0].package_name,
+            }
+            : null;
+        const exercises = exercisedResult.rows.map(row => {
+            const eventCountRaw = Number(row.event_count);
+            const eventCount = Number.isFinite(eventCountRaw) ? eventCountRaw : 0;
+            const eventBreakdownSource = Array.isArray(row.event_breakdown)
+                ? row.event_breakdown
+                : [];
+            const consuming = row.event_kind === 'consuming_choice';
+            return {
+                updateId: row.update_id,
+                recordTime: row.record_time,
+                effectiveAt: row.effective_at,
+                choice: row.choice,
+                interfaceId: row.interface_id,
+                eventKind: row.event_kind,
+                consuming,
+                choiceArgument: row.choice_argument,
+                exerciseResult: row.exercise_result,
+                actingParties: row.acting_parties ?? [],
+                templateId: row.template_id,
+                packageName: row.package_name,
+                eventCount,
+                eventBreakdown: eventBreakdownSource.map((item) => {
+                    const countRaw = Number(item.count);
+                    return {
+                        templateName: item.templateName,
+                        packageName: item.packageName,
+                        kind: item.kind,
+                        count: Number.isFinite(countRaw) ? countRaw : 0,
+                    };
+                }),
+            };
+        });
+        return { created, archived, exercises };
+    }
+    /** Execute a query directly on the pool Useful for read operations that don't have dedicated methods */
+    async query(queryText, values) {
+        const result = await this.pool.query(queryText, values);
+        return { rows: result.rows };
+    }
+    /**
+     * Get traffic costs aggregated by round from MemberTraffic events. Queries the
+     * transactions schema for MemberTraffic created events.
+     */
+    async getTrafficCostsByRound(timeRange, timePeriod, customStartDate, partyFilter, providerFilter) {
+        let timeRangeInterval;
+        let timeFilter;
+        switch (timeRange) {
+            case '15m':
+                timeRangeInterval = '15 minutes';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '15 minutes'";
+                break;
+            case '1h':
+                timeRangeInterval = '1 hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 hour'";
+                break;
+            case '6h':
+                timeRangeInterval = '6 hours';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '6 hours'";
+                break;
+            case '1d':
+                timeRangeInterval = '1 day';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 day'";
+                break;
+            case '7d':
+                timeRangeInterval = '7 days';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '7 days'";
+                break;
+            case '30d':
+                timeRangeInterval = '30 days';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '30 days'";
+                break;
+            case 'last-month':
+                timeRangeInterval = '1 month';
+                timeFilter =
+                    "t.record_time >= date_trunc('month', current_date - interval '1 month') AND t.record_time < date_trunc('month', current_date)";
+                break;
+            case 'all':
+                timeRangeInterval = 'all';
+                timeFilter = 'TRUE';
+                break;
+            default:
+                timeRangeInterval = '1 day';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 day'";
+        }
+        if (timePeriod === 'custom-start' && customStartDate) {
+            timeFilter = `t.record_time >= '${customStartDate}:00' AND t.record_time < ('${customStartDate}:00'::timestamp + INTERVAL '${timeRangeInterval}')`;
+        }
+        // Build parameterized query
+        const queryParams = [this.network];
+        let partyCondition = '';
+        let providerCondition = '';
+        if (partyFilter) {
+            queryParams.push(partyFilter);
+            partyCondition = ` AND c.create_argument->>'memberId' = $${queryParams.length}`;
+        }
+        if (providerFilter) {
+            queryParams.push(providerFilter);
+            providerCondition = ` AND p.provider = $${queryParams.length}`;
+        }
+        const query = `
+      WITH traffic_events AS (
+        SELECT
+          t.record_time,
+          FLOOR(EXTRACT(EPOCH FROM t.record_time) / 600) AS round,
+          (c.create_argument->>'amuletSpent')::numeric AS amulet_spent,
+          (c.create_argument->>'usdSpent')::numeric AS usd_spent,
+          (c.create_argument->>'totalPurchased')::numeric AS total_purchased,
+          (c.create_argument->>'numPurchases')::integer AS num_purchases,
+          p.provider
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        LEFT JOIN transaction_providers tp ON tp.transaction_id = t.id
+        LEFT JOIN providers p ON tp.provider_id = p.id
+        WHERE t.network = $1
+          AND ${timeFilter}
+          AND e.kind = 'created'
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.DecentralizedSynchronizer'
+          AND tmpl.template_name = 'MemberTraffic'
+          ${partyCondition}
+          ${providerCondition}
+      ),
+      round_bounds AS (
+        SELECT
+          COALESCE(MIN(round), 0) AS min_round,
+          COALESCE(MAX(round), 0) AS max_round
+        FROM traffic_events
+      ),
+      rounds AS (
+        SELECT generate_series(
+          (SELECT min_round FROM round_bounds),
+          (SELECT max_round FROM round_bounds)
+        ) AS round
+        WHERE (SELECT max_round FROM round_bounds) > 0
+      ),
+      aggregated_traffic AS (
+        SELECT
+          round,
+          MIN(record_time) AS timestamp,
+          COALESCE(SUM(amulet_spent), 0) AS amulet_spent,
+          COALESCE(SUM(usd_spent), 0) AS usd_spent,
+          COALESCE(SUM(total_purchased), 0) AS total_purchased,
+          COALESCE(SUM(num_purchases), 0) AS num_purchases,
+          ARRAY_REMOVE(ARRAY_AGG(DISTINCT provider), NULL) AS providers
+        FROM traffic_events
+        GROUP BY round
+      )
+      SELECT
+        r.round,
+        at.timestamp,
+        COALESCE(at.amulet_spent, 0) AS amulet_spent,
+        COALESCE(at.usd_spent, 0) AS usd_spent,
+        COALESCE(at.total_purchased, 0) AS total_purchased,
+        COALESCE(at.num_purchases, 0) AS num_purchases,
+        COALESCE(at.providers, ARRAY[]::text[]) AS providers
+      FROM rounds r
+      LEFT JOIN aggregated_traffic at ON at.round = r.round
+      ORDER BY r.round ASC
+    `;
+        const result = await this.pool.query(query, queryParams);
+        return result.rows.map(row => ({
+            round: typeof row.round === 'number' ? row.round : parseInt(row.round, 10),
+            timestamp: row.timestamp
+                ? new Date(row.timestamp).toISOString()
+                : new Date().toISOString(),
+            amuletSpent: parseFloat(row.amulet_spent),
+            usdSpent: parseFloat(row.usd_spent),
+            trafficPurchased: parseFloat(row.total_purchased),
+            numPurchases: parseInt(row.num_purchases, 10),
+            providers: Array.isArray(row.providers)
+                ? row.providers
+                : typeof row.providers === 'string'
+                    ? [row.providers]
+                    : [],
+        }));
+    }
+    async getMemberTrafficEvents(timeRange, timePeriod, customStartDate, partyFilter, providerFilter) {
+        let timeFilterCondition = null;
+        let timeRangeInterval = null;
+        switch (timeRange) {
+            case '15m':
+                timeFilterCondition = "t.record_time >= NOW() - INTERVAL '15 minutes'";
+                timeRangeInterval = '15 minutes';
+                break;
+            case '1h':
+                timeFilterCondition = "t.record_time >= NOW() - INTERVAL '1 hour'";
+                timeRangeInterval = '1 hour';
+                break;
+            case '6h':
+                timeFilterCondition = "t.record_time >= NOW() - INTERVAL '6 hours'";
+                timeRangeInterval = '6 hours';
+                break;
+            case '1d':
+                timeFilterCondition = "t.record_time >= NOW() - INTERVAL '1 day'";
+                timeRangeInterval = '1 day';
+                break;
+            case '7d':
+                timeFilterCondition = "t.record_time >= NOW() - INTERVAL '7 days'";
+                timeRangeInterval = '7 days';
+                break;
+            case '30d':
+                timeFilterCondition = "t.record_time >= NOW() - INTERVAL '30 days'";
+                timeRangeInterval = '30 days';
+                break;
+            case 'last-month':
+                timeFilterCondition =
+                    "t.record_time >= date_trunc('month', current_date - interval '1 month') AND t.record_time < date_trunc('month', current_date)";
+                timeRangeInterval = '1 month';
+                break;
+            case 'all':
+            default:
+                timeFilterCondition = null;
+                timeRangeInterval = null;
+                break;
+        }
+        if (timePeriod === 'custom-start' && customStartDate) {
+            const interval = timeRangeInterval ?? '30 days';
+            timeFilterCondition = `t.record_time >= '${customStartDate}:00' AND t.record_time < ('${customStartDate}:00'::timestamp + INTERVAL '${interval}')`;
+        }
+        const queryParams = [this.network];
+        const conditions = [
+            't.network = $1',
+            "e.kind = 'created'",
+            "tmpl.package_name = 'splice-amulet'",
+            "tmpl.module_name = 'Splice.DecentralizedSynchronizer'",
+            "tmpl.template_name = 'MemberTraffic'",
+        ];
+        if (timeFilterCondition) {
+            conditions.push(timeFilterCondition);
+        }
+        if (partyFilter) {
+            queryParams.push(partyFilter);
+            conditions.push(`c.create_argument->>'memberId' = $${queryParams.length}`);
+        }
+        if (providerFilter) {
+            queryParams.push(providerFilter);
+            conditions.push(`p.provider = $${queryParams.length}`);
+        }
+        const query = `
+      SELECT
+        t.record_time AS record_time,
+        FLOOR(EXTRACT(EPOCH FROM t.record_time) / 600) AS round,
+        (c.create_argument->>'amuletSpent')::numeric AS amulet_spent,
+        (c.create_argument->>'usdSpent')::numeric AS usd_spent,
+        (c.create_argument->>'totalPurchased')::numeric AS total_purchased,
+        e.contract_id,
+        t.update_id,
+        c.create_argument->>'memberId' AS member_id,
+        MAX(tp.ledger_offset) AS ledger_offset,
+        ARRAY_REMOVE(ARRAY_AGG(DISTINCT p.provider), NULL) AS providers,
+        ARRAY_REMOVE(
+          ARRAY_AGG(
+            DISTINCT CASE
+              WHEN act.party_id IS NOT NULL
+                   AND act.party_id <> c.create_argument->>'memberId'
+                   AND tea.actor_type = 'signatory'
+              THEN act.party_id
+              ELSE NULL
+            END
+          ),
+          NULL
+        ) AS payer_parties
+      FROM transactions t
+      JOIN transaction_events e ON e.transaction_id = t.id
+      JOIN contracts c ON c.id = e.contract_id
+      JOIN templates tmpl ON c.template_id = tmpl.id
+      LEFT JOIN transaction_providers tp ON tp.transaction_id = t.id
+      LEFT JOIN providers p ON tp.provider_id = p.id
+      LEFT JOIN contract_actors tea ON tea.contract_id = e.contract_id AND tea.actor_type = 'signatory'
+      LEFT JOIN parties act ON act.id = tea.party_id
+      WHERE ${conditions.join('\n        AND ')}
+      GROUP BY
+        t.record_time,
+        round,
+        amulet_spent,
+        usd_spent,
+        total_purchased,
+        e.contract_id,
+        t.update_id,
+        member_id
+      ORDER BY t.record_time ASC
+    `;
+        const normalizeTextArray = (value) => {
+            if (Array.isArray(value)) {
+                return value.filter((item) => typeof item === 'string');
+            }
+            if (typeof value === 'string') {
+                const trimmed = value.trim();
+                if (!trimmed || trimmed === '{}') {
+                    return [];
+                }
+                const withoutBraces = trimmed.replace(/^{|}$/g, '');
+                return withoutBraces
+                    .split(',')
+                    .map(item => item.replace(/^"|"$/g, '').trim())
+                    .filter(Boolean);
+            }
+            return [];
+        };
+        const result = await this.pool.query(query, queryParams);
+        return result.rows.map(row => ({
+            round: typeof row.round === 'number' ? row.round : parseInt(row.round, 10),
+            timestamp: row.record_time
+                ? new Date(row.record_time).toISOString()
+                : new Date().toISOString(),
+            amuletSpent: parseFloat(row.amulet_spent),
+            usdSpent: parseFloat(row.usd_spent),
+            trafficPurchased: parseFloat(row.total_purchased),
+            contractId: row.contract_id,
+            updateId: row.update_id,
+            ledgerOffset: row.ledger_offset != null ? parseInt(row.ledger_offset, 10) : undefined,
+            providers: normalizeTextArray(row.providers),
+            payerParties: normalizeTextArray(row.payer_parties),
+        }));
+    }
+    /** Get all available providers for a network */
+    async getAvailableProviders() {
+        const query = `
+      SELECT DISTINCT provider, synchronizer_id
+      FROM providers
+      WHERE network = $1
+      ORDER BY provider
+    `;
+        const result = await this.pool.query(query, [this.network]);
+        return result.rows.map(row => ({
+            provider: row.provider,
+            synchronizer_id: row.synchronizer_id,
+        }));
+    }
+    /** Get member traffic history for a specific party Returns all MemberTraffic events for the given party ID */
+    async getMemberTrafficHistory(partyId) {
+        const query = `
+      SELECT
+        tp.ledger_offset AS offset,
+        t.record_time AS created_at,
+        c.create_argument->>'memberId' AS member_id,
+        c.create_argument->>'totalPurchased' AS total_purchased,
+        c.create_argument->>'numPurchases' AS num_purchases,
+        c.create_argument->>'amuletSpent' AS amulet_spent,
+        c.create_argument->>'usdSpent' AS usd_spent
+      FROM transactions t
+      JOIN transaction_providers tp ON tp.transaction_id = t.id
+      JOIN transaction_events e ON e.transaction_id = t.id
+      JOIN contracts c ON c.id = e.contract_id
+      JOIN templates tmpl ON c.template_id = tmpl.id
+      WHERE t.network = $1
+        AND e.kind = 'created'
+        AND tmpl.package_name = 'splice-amulet'
+        AND tmpl.module_name = 'Splice.DecentralizedSynchronizer'
+        AND tmpl.template_name = 'MemberTraffic'
+        AND c.create_argument->>'memberId' = $2
+      ORDER BY t.record_time DESC
+    `;
+        const result = await this.pool.query(query, [this.network, partyId]);
+        return result.rows.map(row => ({
+            offset: parseInt(row.offset, 10),
+            createdAt: new Date(row.created_at).toISOString(),
+            memberId: row.member_id,
+            totalPurchased: row.total_purchased,
+            numPurchases: row.num_purchases,
+            amuletSpent: row.amulet_spent,
+            usdSpent: row.usd_spent,
+        }));
+    }
+    // Compatibility wrappers for actor inserts
+    async insertSignatories(contractId, partyIds, client = this.pool) {
+        await this.insertActors(contractId, partyIds, 'signatory', this.network, client);
+    }
+    async insertObservers(contractId, partyIds, client = this.pool) {
+        await this.insertActors(contractId, partyIds, 'observer', this.network, client);
+    }
+    // Deprecated in V2 schema: create payload stored on contracts.create_argument
+    async bulkInsertCantonTransactionEventCreated(_details, _client = this.pool) {
+        throw new Error('bulkInsertCantonTransactionEventCreated is deprecated; use contracts.create_argument instead.');
+    }
+    /**
+     * Latest offset and last transaction time for a provider.
+     */
+    async getProviderOffset(provider) {
+        const query = `
+      SELECT
+        MAX(tp.ledger_offset) AS last_offset,
+        MAX(t.record_time) AS last_updated
+      FROM transaction_providers tp
+      INNER JOIN providers p ON tp.provider_id = p.id
+      INNER JOIN transactions t ON tp.transaction_id = t.id
+      WHERE p.network = $1 AND p.provider = $2
+    `;
+        const result = await this.pool.query(query, [this.network, provider]);
+        if (result.rows.length === 0) {
+            return { last_offset: null, last_updated: null };
+        }
+        const row = result.rows[0];
+        return {
+            last_offset: row.last_offset !== null && row.last_offset !== undefined
+                ? Number(row.last_offset)
+                : null,
+            last_updated: row.last_updated ?? null,
+        };
+    }
+    /**
+     * Active Amulet contracts grouped by owner (signatory). Filters out DSO and empty owners.
+     */
+    async getActiveAmuletContractsByOwner() {
+        const query = `
+      WITH amulet_contracts AS (
+        SELECT
+          c.id AS contract_id
+        FROM contracts c
+        INNER JOIN templates t ON t.id = c.template_id
+        WHERE c.network = $1
+          AND t.package_name = 'splice-amulet'
+          AND t.module_name = 'Splice.Amulet'
+          AND t.template_name = 'Amulet'
+      ),
+      active AS (
+        SELECT contract_id
+        FROM active_contracts ac
+        WHERE ac.contract_id IN (SELECT contract_id FROM amulet_contracts)
+      ),
+      signatories AS (
+        SELECT
+          ca.contract_id,
+          TRIM(p.party_id)::text AS owner
+        FROM contract_actors ca
+        INNER JOIN parties p ON p.id = ca.party_id
+        WHERE ca.actor_type = 'signatory'
+          AND p.network = $1
+      )
+      SELECT
+        s.owner,
+        COUNT(*)::bigint AS contract_count
+      FROM active a
+      INNER JOIN signatories s ON s.contract_id = a.contract_id
+      WHERE s.owner IS NOT NULL
+        AND s.owner <> ''
+        AND s.owner NOT ILIKE 'DSO::%'
+      GROUP BY s.owner
+      ORDER BY contract_count DESC, s.owner
+    `;
+        const result = await this.pool.query(query, [this.network]);
+        return result.rows.map(row => ({
+            owner: row.owner,
+            contract_count: Number(row.contract_count) || 0,
+        }));
+    }
+    /**
+     * Locked amulets for a signatory or owner. Filters to active contracts.
+     */
+    async getLockedAmuletsBySignatory(partyId) {
+        if (!partyId) {
+            throw new Error('partyId is required to fetch LockedAmulets');
+        }
+        const query = `
+      WITH locked_amulets AS (
+        SELECT
+          c.id AS contract_db_id,
+          c.canton_contract_id,
+          t.update_id,
+          t.record_time,
+          pkg.package_id,
+          tmpl.module_name,
+          tmpl.template_name,
+          c.create_argument,
+          COALESCE(
+            json_agg(DISTINCT CASE WHEN ca.actor_type = 'signatory' THEN p.party_id END)
+              FILTER (WHERE p.party_id IS NOT NULL),
+            '[]'::json
+          ) AS signatories,
+          COALESCE(
+            json_agg(DISTINCT CASE WHEN ca.actor_type = 'observer' THEN p.party_id END)
+              FILTER (WHERE p.party_id IS NOT NULL),
+            '[]'::json
+          ) AS observers
+        FROM transactions t
+        INNER JOIN transaction_events e ON e.transaction_id = t.id
+        INNER JOIN contracts c ON c.id = e.contract_id
+        INNER JOIN templates tmpl ON tmpl.id = c.template_id
+        INNER JOIN packages pkg ON pkg.id = e.package_id
+        LEFT JOIN contract_actors ca ON ca.contract_id = c.id
+        LEFT JOIN parties p ON p.id = ca.party_id
+        WHERE
+          t.network = $1
+          AND e.kind = 'created'
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'LockedAmulet'
+          AND (
+            EXISTS (
+              SELECT 1
+              FROM contract_actors ca_filter
+              INNER JOIN parties p_filter ON ca_filter.party_id = p_filter.id
+              WHERE ca_filter.contract_id = c.id
+                AND ca_filter.actor_type = 'signatory'
+                AND p_filter.party_id = $2
+                AND p_filter.network = $1
+            )
+            OR c.create_argument::jsonb -> 'amulet' ->> 'owner' = $2
+          )
+        GROUP BY
+          c.id,
+          c.canton_contract_id,
+          t.update_id,
+          t.record_time,
+          pkg.package_id,
+          tmpl.module_name,
+          tmpl.template_name,
+          c.create_argument
+      )
+      SELECT *
+      FROM locked_amulets la
+      WHERE EXISTS (SELECT 1 FROM active_contracts ac WHERE ac.contract_id = la.contract_db_id)
+      ORDER BY la.record_time DESC
+    `;
+        const result = await this.pool.query(query, [this.network, partyId]);
+        const ensureStringArray = (value) => {
+            if (Array.isArray(value)) {
+                return value.filter((item) => typeof item === 'string');
+            }
+            if (value === null || value === undefined) {
+                return [];
+            }
+            if (typeof value === 'string') {
+                try {
+                    const parsed = JSON.parse(value);
+                    if (Array.isArray(parsed)) {
+                        return parsed.filter((item) => typeof item === 'string');
+                    }
+                }
+                catch {
+                    const trimmed = value.trim();
+                    if (trimmed.startsWith('{') && trimmed.endsWith('}')) {
+                        return trimmed
+                            .slice(1, -1)
+                            .split(',')
+                            .map(item => item.replace(/^"|"$/g, '').trim())
+                            .filter(Boolean);
+                    }
+                }
+            }
+            return [];
+        };
+        const toIsoString = (value) => {
+            if (!value) {
+                return new Date(0).toISOString();
+            }
+            const dateValue = value instanceof Date ? value : new Date(value);
+            if (Number.isNaN(dateValue.getTime())) {
+                return new Date(0).toISOString();
+            }
+            return dateValue.toISOString();
+        };
+        return result.rows.map(row => {
+            const createArgumentRaw = row.create_argument;
+            let createArgument = null;
+            if (createArgumentRaw && typeof createArgumentRaw === 'object') {
+                createArgument = createArgumentRaw;
+            }
+            else if (typeof createArgumentRaw === 'string') {
+                try {
+                    createArgument = JSON.parse(createArgumentRaw);
+                }
+                catch {
+                    createArgument = null;
+                }
+            }
+            let owner = null;
+            let amountRaw = null;
+            let amount = null;
+            if (createArgument && 'amulet' in createArgument) {
+                const amuletCandidate = createArgument['amulet'];
+                if (amuletCandidate &&
+                    typeof amuletCandidate === 'object' &&
+                    !Array.isArray(amuletCandidate)) {
+                    const amuletObj = amuletCandidate;
+                    const ownerCandidate = amuletObj['owner'];
+                    owner = typeof ownerCandidate === 'string' ? ownerCandidate : null;
+                    const amountCandidate = amuletObj['amount'];
+                    if (typeof amountCandidate === 'string') {
+                        amountRaw = amountCandidate;
+                    }
+                    else if (amountCandidate &&
+                        typeof amountCandidate === 'object' &&
+                        !Array.isArray(amountCandidate)) {
+                        const amountObj = amountCandidate;
+                        const initialAmount = amountObj['initialAmount'];
+                        if (typeof initialAmount === 'string') {
+                            amountRaw = initialAmount;
+                        }
+                        else {
+                            const nestedAmount = amountObj['amount'];
+                            if (typeof nestedAmount === 'string') {
+                                amountRaw = nestedAmount;
+                            }
+                        }
+                    }
+                    else if (typeof amountCandidate === 'number') {
+                        amountRaw = amountCandidate.toString();
+                    }
+                    if (amountRaw) {
+                        const parsed = Number.parseFloat(amountRaw);
+                        amount = Number.isFinite(parsed) ? parsed : null;
+                    }
+                }
+            }
+            let lockExpiresAt = null;
+            let lockDescription = null;
+            let lockHolders = [];
+            if (createArgument && 'lock' in createArgument) {
+                const lockCandidate = createArgument['lock'];
+                if (lockCandidate &&
+                    typeof lockCandidate === 'object' &&
+                    !Array.isArray(lockCandidate)) {
+                    const lockObj = lockCandidate;
+                    const expiresCandidate = lockObj['expiresAt'];
+                    if (typeof expiresCandidate === 'string') {
+                        lockExpiresAt = expiresCandidate;
+                    }
+                    const descriptionCandidate = lockObj['optContext'];
+                    if (typeof descriptionCandidate === 'string') {
+                        lockDescription = descriptionCandidate;
+                    }
+                    const holdersCandidate = lockObj['holders'];
+                    if (Array.isArray(holdersCandidate)) {
+                        lockHolders = holdersCandidate.filter((item) => typeof item === 'string');
+                    }
+                }
+            }
+            const templateIdParts = [
+                typeof row.package_id === 'string' ? row.package_id : null,
+                typeof row.module_name === 'string' ? row.module_name : null,
+                typeof row.template_name === 'string' ? row.template_name : null,
+            ].filter((part) => part !== null);
+            const templateId = templateIdParts.join(':');
+            return {
+                contractId: row.canton_contract_id ?? '',
+                updateId: row.update_id ?? '',
+                createdAt: toIsoString(row.record_time),
+                owner,
+                amount,
+                amountRaw,
+                lockExpiresAt,
+                lockHolders,
+                lockDescription,
+                signatories: ensureStringArray(row.signatories),
+                observers: ensureStringArray(row.observers),
+                templateId,
+            };
+        });
+    }
+    /**
+     * Transaction lookup by updateId or offset with aggregated tree data.
+     * Returns a shape compatible with UI transaction-tree expectations.
+     */
+    async getTransactionTree(search) {
+        // 1) Locate transaction
+        let txQuery;
+        let txParams;
+        if (search.type === 'updateId') {
+            txQuery = `
+        SELECT
+          t.id,
+          t.update_id,
+          t.command_id,
+          t.workflow_id,
+          t.effective_at,
+          t.record_time,
+          MAX(tp.ledger_offset) AS ledger_offset
+        FROM transactions t
+        LEFT JOIN transaction_providers tp ON tp.transaction_id = t.id
+        WHERE t.network = $1 AND t.update_id = $2
+        GROUP BY t.id, t.update_id, t.command_id, t.workflow_id, t.effective_at, t.record_time
+      `;
+            txParams = [this.network, search.value];
+        }
+        else {
+            txQuery = `
+        SELECT
+          t.id,
+          t.update_id,
+          t.command_id,
+          t.workflow_id,
+          t.effective_at,
+          t.record_time,
+          tp.ledger_offset
+        FROM transactions t
+        INNER JOIN transaction_providers tp ON tp.transaction_id = t.id
+        INNER JOIN providers p ON p.id = tp.provider_id
+        WHERE t.network = $1 AND p.network = $1 AND tp.ledger_offset = $2
+        LIMIT 1
+      `;
+            txParams = [this.network, search.value];
+        }
+        const txResult = await this.pool.query(txQuery, txParams);
+        if (txResult.rows.length === 0) {
+            throw new Error('Transaction not found');
+        }
+        const txRow = txResult.rows[0];
+        const transactionId = txRow.id;
+        // 2) Fetch canonical events with provider/node + template info
+        const eventsQuery = `
+      SELECT
+        e.id,
+        e.kind,
+        e.contract_id,
+        e.package_id,
+        c.canton_contract_id,
+        tplt.module_name,
+        tplt.template_name,
+        tplt.package_name,
+        pkg.package_id AS package_hash,
+        ep.node_id,
+        p.provider,
+        tp.ledger_offset
+      FROM transaction_events e
+      INNER JOIN contracts c ON c.id = e.contract_id
+      INNER JOIN templates tplt ON tplt.id = c.template_id
+      INNER JOIN packages pkg ON pkg.id = e.package_id
+      INNER JOIN transaction_event_providers ep ON ep.event_id = e.id
+      INNER JOIN providers p ON p.id = ep.provider_id
+      INNER JOIN transaction_providers tp ON tp.transaction_id = e.transaction_id AND tp.provider_id = ep.provider_id
+      WHERE e.transaction_id = $1
+      ORDER BY e.id, ep.node_id
+    `;
+        const eventsResult = await this.pool.query(eventsQuery, [transactionId]);
+        const eventRows = eventsResult.rows;
+        if (eventRows.length === 0) {
+            return {
+                transaction: {
+                    updateId: txRow.update_id ?? undefined,
+                    commandId: txRow.command_id ?? undefined,
+                    workflowId: txRow.workflow_id ?? undefined,
+                    effectiveAt: txRow.effective_at?.toISOString?.() ?? txRow.effective_at,
+                    recordTime: txRow.record_time?.toISOString?.() ?? txRow.record_time,
+                    offset: txRow.ledger_offset ? String(txRow.ledger_offset) : undefined,
+                    traceContext: txRow.trace_context ?? undefined,
+                    eventsById: {},
+                },
+            };
+        }
+        const eventIds = Array.from(new Set(eventRows.map(r => r.id)));
+        const contractIds = Array.from(new Set(eventRows.map(r => r.contract_id)));
+        // 3) Exercised details
+        const exercisedDetailsQuery = `
+      SELECT
+        ex.event_id,
+        ex.interface_id,
+        ch.choice,
+        ex.choice_argument,
+        ex.exercise_result
+      FROM transaction_events_exercised ex
+      INNER JOIN choices ch ON ch.id = ex.choice_id
+      WHERE ex.event_id = ANY($1)
+    `;
+        const exercisedDetailsResult = await this.pool.query(exercisedDetailsQuery, [eventIds]);
+        const exercisedDetailsMap = new Map(exercisedDetailsResult.rows.map(row => [row.event_id, row]));
+        // 4) Acting parties
+        const actingPartiesQuery = `
+      SELECT
+        ap.event_id,
+        parties.party_id
+      FROM transaction_events_exercised_acting_parties ap
+      INNER JOIN parties ON parties.id = ap.party_id
+      WHERE parties.network = $1 AND ap.event_id = ANY($2)
+    `;
+        const actingPartiesResult = await this.pool.query(actingPartiesQuery, [
+            this.network,
+            eventIds,
+        ]);
+        const actingByEvent = new Map();
+        actingPartiesResult.rows.forEach(row => {
+            const list = actingByEvent.get(row.event_id) ?? [];
+            list.push(row.party_id);
+            actingByEvent.set(row.event_id, list);
+        });
+        // 5) Contract actors (signatories/observers) at contract level
+        const contractActorsQuery = `
+      SELECT
+        ca.contract_id,
+        ca.actor_type,
+        p.party_id
+      FROM contract_actors ca
+      INNER JOIN parties p ON p.id = ca.party_id
+      WHERE p.network = $1 AND ca.contract_id = ANY($2)
+    `;
+        const contractActorsResult = await this.pool.query(contractActorsQuery, [
+            this.network,
+            contractIds,
+        ]);
+        const signatoriesByContract = new Map();
+        const observersByContract = new Map();
+        contractActorsResult.rows.forEach(row => {
+            if (row.actor_type === 'signatory') {
+                const list = signatoriesByContract.get(row.contract_id) ?? [];
+                list.push(row.party_id);
+                signatoriesByContract.set(row.contract_id, list);
+            }
+            if (row.actor_type === 'observer') {
+                const list = observersByContract.get(row.contract_id) ?? [];
+                list.push(row.party_id);
+                observersByContract.set(row.contract_id, list);
+            }
+        });
+        // 6) Build event objects
+        const eventsById = {};
+        eventRows.forEach(row => {
+            const canonicalKind = row.kind === 'consuming_choice' || row.kind === 'non_consuming_choice'
+                ? 'exercised'
+                : row.kind;
+            const consuming = row.kind === 'consuming_choice'
+                ? true
+                : row.kind === 'non_consuming_choice'
+                    ? false
+                    : undefined;
+            const exercisedDetails = exercisedDetailsMap.get(row.id);
+            const acting = actingByEvent.get(row.id) ?? [];
+            const signatories = signatoriesByContract.get(row.contract_id) ?? [];
+            const observers = observersByContract.get(row.contract_id) ?? [];
+            const base = {
+                contractId: row.canton_contract_id,
+                templateId: row.template_name,
+                packageName: row.package_name,
+                offset: row.ledger_offset ? String(row.ledger_offset) : undefined,
+                nodeId: row.node_id ? String(row.node_id) : undefined,
+                provider: row.provider,
+                reassignmentCounter: '0',
+            };
+            if (canonicalKind === 'created') {
+                eventsById[row.id] = {
+                    CreatedTreeEvent: {
+                        value: {
+                            contractId: base.contractId,
+                            templateId: `${row.package_name}:${row.module_name}:${row.template_name}`,
+                            packageName: row.package_name,
+                            createdAt: txRow.record_time?.toISOString?.() ?? txRow.record_time,
+                            createArgument: undefined,
+                            offset: base.offset,
+                            reassignmentCounter: base.reassignmentCounter,
+                            nodeId: base.nodeId,
+                            contractKey: undefined,
+                            signatories,
+                            observers,
+                        },
+                    },
+                };
+            }
+            else if (canonicalKind === 'archived') {
+                eventsById[row.id] = {
+                    ArchivedTreeEvent: {
+                        value: {
+                            contractId: base.contractId,
+                            templateId: `${row.package_name}:${row.module_name}:${row.template_name}`,
+                            packageName: row.package_name,
+                            offset: base.offset,
+                            reassignmentCounter: base.reassignmentCounter,
+                            nodeId: base.nodeId,
+                        },
+                    },
+                };
+            }
+            else {
+                eventsById[row.id] = {
+                    ExercisedTreeEvent: {
+                        value: {
+                            contractId: base.contractId,
+                            templateId: `${row.package_name}:${row.module_name}:${row.template_name}`,
+                            packageName: row.package_name,
+                            interfaceId: exercisedDetails?.interface_id ?? undefined,
+                            choice: exercisedDetails?.choice ?? undefined,
+                            choiceArgument: exercisedDetails?.choice_argument ?? undefined,
+                            actingParties: acting,
+                            consuming,
+                            witnessParties: [],
+                            lastDescendantNodeId: undefined,
+                            exerciseResult: exercisedDetails?.exercise_result ?? undefined,
+                            offset: base.offset,
+                            reassignmentCounter: base.reassignmentCounter,
+                            nodeId: base.nodeId,
+                        },
+                    },
+                };
+            }
+        });
+        return {
+            transaction: {
+                updateId: txRow.update_id ?? undefined,
+                commandId: txRow.command_id ?? undefined,
+                workflowId: txRow.workflow_id ?? undefined,
+                effectiveAt: txRow.effective_at?.toISOString?.() ?? txRow.effective_at,
+                recordTime: txRow.record_time?.toISOString?.() ?? txRow.record_time,
+                offset: txRow.ledger_offset ? String(txRow.ledger_offset) : undefined,
+                traceContext: txRow.trace_context ?? undefined,
+                eventsById,
+            },
+        };
+    }
+    /**
+     * Given a canton_contract_id, return related transactions (newest first).
+     */
+    async findTransactionsByCantonContractId(cantonContractId) {
+        const query = `
+      SELECT DISTINCT
+        t.update_id,
+        t.record_time,
+        e.kind
+      FROM contracts c
+      INNER JOIN transaction_events e ON e.contract_id = c.id
+      INNER JOIN transactions t ON t.id = e.transaction_id
+      WHERE c.network = $1 AND c.canton_contract_id = $2
+      ORDER BY t.record_time DESC
+    `;
+        const result = await this.pool.query(query, [
+            this.network,
+            cantonContractId,
+        ]);
+        return result.rows;
+    }
+    /**
+     * Stats for a party (signatory/observer via contract_actors, acting via exercised_acting_parties).
+     */
+    async getPartyStats(partyId) {
+        const query = `
+      WITH party_row AS (
+        SELECT id FROM parties WHERE party_id = $1 AND network = $2
+      ),
+      party_events AS (
+        SELECT DISTINCT e.id, e.transaction_id, e.contract_id, e.template_id, e.kind, t.record_time
+        FROM transaction_events e
+        INNER JOIN transactions t ON t.id = e.transaction_id
+        WHERE t.network = $2
+          AND (
+            EXISTS (
+              SELECT 1
+              FROM contract_actors ca
+              WHERE ca.contract_id = e.contract_id
+                AND ca.party_id = (SELECT id FROM party_row)
+            )
+            OR EXISTS (
+              SELECT 1
+              FROM transaction_events_exercised_acting_parties ap
+              WHERE ap.event_id = e.id
+                AND ap.party_id = (SELECT id FROM party_row)
+            )
+          )
+      )
+      SELECT
+        COUNT(DISTINCT transaction_id)::int AS total_transactions,
+        COUNT(*)::int AS total_events,
+        COUNT(DISTINCT CASE WHEN kind = 'created' THEN id END)::int AS contracts_created,
+        COUNT(DISTINCT CASE WHEN kind IN ('consuming_choice','non_consuming_choice') THEN id END)::int AS contracts_exercised,
+        COUNT(DISTINCT CASE WHEN kind = 'archived' THEN id END)::int AS contracts_archived,
+        COUNT(DISTINCT contract_id)::int AS unique_contracts,
+        COUNT(DISTINCT template_id)::int AS unique_templates,
+        MIN(record_time)::text AS first_seen,
+        MAX(record_time)::text AS last_seen
+      FROM party_events;
+    `;
+        const result = await this.pool.query(query, [partyId, this.network]);
+        if (result.rows.length === 0) {
+            return {
+                total_transactions: 0,
+                total_events: 0,
+                contracts_created: 0,
+                contracts_exercised: 0,
+                contracts_archived: 0,
+                unique_contracts: 0,
+                unique_templates: 0,
+                first_seen: null,
+                last_seen: null,
+            };
+        }
+        return result.rows[0];
+    }
+    async getPartyTopChoices(partyId, limit = 10) {
+        const query = `
+      WITH party_row AS (
+        SELECT id FROM parties WHERE party_id = $1 AND network = $2
+      )
+      SELECT
+        ch.choice AS choice_name,
+        COUNT(*)::int AS exercise_count
+      FROM transaction_events e
+      INNER JOIN transaction_events_exercised ex ON ex.event_id = e.id
+      INNER JOIN choices ch ON ch.id = ex.choice_id
+      WHERE e.kind IN ('consuming_choice','non_consuming_choice')
+        AND EXISTS (
+          SELECT 1
+          FROM transaction_events_exercised_acting_parties ap
+          WHERE ap.event_id = e.id
+            AND ap.party_id = (SELECT id FROM party_row)
+        )
+      GROUP BY ch.choice
+      ORDER BY exercise_count DESC
+      LIMIT $3
+    `;
+        const result = await this.pool.query(query, [partyId, this.network, limit]);
+        return result.rows;
+    }
+    async getPartyTopTemplates(partyId, limit = 10) {
+        const query = `
+      WITH party_row AS (
+        SELECT id FROM parties WHERE party_id = $1 AND network = $2
+      ),
+      party_events AS (
+        SELECT DISTINCT e.id, e.template_id, e.kind
+        FROM transaction_events e
+        INNER JOIN transactions t ON t.id = e.transaction_id
+        WHERE t.network = $2
+          AND (
+            EXISTS (
+              SELECT 1
+              FROM contract_actors ca
+              WHERE ca.contract_id = e.contract_id
+                AND ca.party_id = (SELECT id FROM party_row)
+            )
+            OR EXISTS (
+              SELECT 1
+              FROM transaction_events_exercised_acting_parties ap
+              WHERE ap.event_id = e.id
+                AND ap.party_id = (SELECT id FROM party_row)
+            )
+          )
+      )
+      SELECT
+        tpl.template_name,
+        COUNT(*)::int AS event_count,
+        COUNT(CASE WHEN pe.kind = 'created' THEN 1 END)::int AS created_count,
+        COUNT(CASE WHEN pe.kind IN ('consuming_choice','non_consuming_choice') THEN 1 END)::int AS exercised_count,
+        COUNT(CASE WHEN pe.kind = 'archived' THEN 1 END)::int AS archived_count
+      FROM party_events pe
+      INNER JOIN templates tpl ON tpl.id = pe.template_id
+      GROUP BY tpl.template_name
+      ORDER BY event_count DESC
+      LIMIT $3
+    `;
+        const result = await this.pool.query(query, [partyId, this.network, limit]);
+        return result.rows;
+    }
+    /**
+     * Paginated transactions for a party with role and summary filters.
+     */
+    async getPartyTransactions(options) {
+        const { partyId, role, templateName, choiceName, limit, offset } = options;
+        const roleFilter = role === 'signatory'
+            ? 'AND is_signatory = true'
+            : role === 'observer'
+                ? 'AND is_observer = true'
+                : role === 'acting'
+                    ? 'AND is_acting = true'
+                    : '';
+        const templateFilter = templateName
+            ? `
+        AND EXISTS (
+          SELECT 1
+          FROM transaction_events tef
+          INNER JOIN templates tf ON tf.id = tef.template_id
+          WHERE tef.transaction_id = tx.id
+            AND tf.template_name = $5
+        )
+      `
+            : '';
+        const choiceFilter = choiceName
+            ? `
+        AND EXISTS (
+          SELECT 1
+          FROM transaction_events tec
+          INNER JOIN transaction_events_exercised ex ON ex.event_id = tec.id
+          INNER JOIN choices ch ON ch.id = ex.choice_id
+          WHERE tec.transaction_id = tx.id
+            AND ch.choice = $6
+        )
+      `
+            : '';
+        const params = [
+            partyId,
+            this.network,
+            limit,
+            offset,
+        ];
+        if (templateName)
+            params.push(templateName);
+        if (choiceName)
+            params.push(choiceName);
+        const query = `
+      WITH party_row AS (
+        SELECT id FROM parties WHERE party_id = $1 AND network = $2
+      ),
+      roles AS (
+        SELECT
+          tx.id as transaction_id,
+          tx.update_id,
+          tx.record_time,
+          -- Roles
+          EXISTS (
+            SELECT 1
+            FROM contract_actors ca
+            WHERE ca.contract_id = ev.contract_id
+              AND ca.party_id = (SELECT id FROM party_row)
+              AND ca.actor_type = 'signatory'
+          ) AS is_signatory,
+          EXISTS (
+            SELECT 1
+            FROM contract_actors ca
+            WHERE ca.contract_id = ev.contract_id
+              AND ca.party_id = (SELECT id FROM party_row)
+              AND ca.actor_type = 'observer'
+          ) AS is_observer,
+          EXISTS (
+            SELECT 1
+            FROM transaction_events_exercised_acting_parties ap
+            WHERE ap.event_id = ev.id
+              AND ap.party_id = (SELECT id FROM party_row)
+          ) AS is_acting
+        FROM transactions tx
+        INNER JOIN transaction_events ev ON ev.transaction_id = tx.id
+        WHERE tx.network = $2
+      ),
+      filtered AS (
+        SELECT DISTINCT *
+        FROM roles
+        WHERE (is_signatory OR is_observer OR is_acting)
+        ${roleFilter}
+      )
+      SELECT
+        f.transaction_id,
+        f.update_id,
+        f.record_time,
+        ARRAY(
+          SELECT DISTINCT role_name FROM (
+            SELECT CASE WHEN f.is_signatory THEN 'signatory' END AS role_name
+            UNION ALL
+            SELECT CASE WHEN f.is_observer THEN 'observer' END AS role_name
+            UNION ALL
+            SELECT CASE WHEN f.is_acting THEN 'acting' END AS role_name
+          ) roles_flat
+          WHERE role_name IS NOT NULL
+        ) AS roles,
+        (
+          SELECT jsonb_agg(
+            jsonb_build_object(
+              'template_name', tpl.template_name,
+              'kind', ev.kind,
+              'count', COUNT(*)::int
+            )
+            ORDER BY COUNT(*) DESC
+          )
+          FROM transaction_events ev
+          INNER JOIN templates tpl ON tpl.id = ev.template_id
+          WHERE ev.transaction_id = f.transaction_id
+        ) AS event_summary
+      FROM filtered f
+      INNER JOIN transactions tx ON tx.id = f.transaction_id
+      WHERE tx.network = $2
+      ${templateFilter}
+      ${choiceFilter}
+      ORDER BY f.record_time DESC
+      LIMIT $3 OFFSET $4
+    `;
+        const result = await this.pool.query(query, params);
+        return result.rows.map(row => ({
+            transaction_id: Number(row.transaction_id),
+            update_id: row.update_id,
+            record_time: row.record_time,
+            roles: row.roles ?? [],
+            event_summary: row.event_summary ?? [],
+        }));
+    }
+    /**
+     * Get AppRewardCoupon time series data from Canton transactions
+     * Queries AppRewardCoupon created events and aggregates by time interval
+     */
+    async getAppRewardCouponTimeSeriesData(timeRange, metric, timePeriod, customStartDate, partyFilter, couponStatus = 'good') {
+        let interval;
+        let timeFilter;
+        let timeSeriesStart;
+        let timeSeriesEnd = 'NOW()';
+        let timeRangeInterval;
+        switch (timeRange) {
+            case '15m':
+                interval = 'minute';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '15 minutes'";
+                timeRangeInterval = '15 minutes';
+                timeSeriesStart = "NOW() - INTERVAL '15 minutes'";
+                break;
+            case '1h':
+                interval = 'minute';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 hour'";
+                timeRangeInterval = '1 hour';
+                timeSeriesStart = "NOW() - INTERVAL '1 hour'";
+                break;
+            case '6h':
+                interval = 'minute';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '6 hours'";
+                timeRangeInterval = '6 hours';
+                timeSeriesStart = "NOW() - INTERVAL '6 hours'";
+                break;
+            case '1d':
+                interval = 'hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 day'";
+                timeRangeInterval = '1 day';
+                timeSeriesStart = "NOW() - INTERVAL '1 day'";
+                break;
+            case '7d':
+                interval = 'hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '7 days'";
+                timeRangeInterval = '7 days';
+                timeSeriesStart = "NOW() - INTERVAL '7 days'";
+                break;
+            case '30d':
+                interval = 'day';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '30 days'";
+                timeRangeInterval = '30 days';
+                timeSeriesStart = "NOW() - INTERVAL '30 days'";
+                break;
+            case 'last-month':
+                interval = 'day';
+                timeFilter =
+                    "t.record_time >= date_trunc('month', current_date - interval '1 month') AND t.record_time < date_trunc('month', current_date)";
+                timeRangeInterval = '1 month';
+                timeSeriesStart =
+                    "date_trunc('month', current_date - interval '1 month')";
+                timeSeriesEnd = "date_trunc('month', current_date)";
+                break;
+            case 'all':
+                interval = 'day';
+                timeFilter = 'TRUE';
+                timeRangeInterval = '100 years';
+                // For 'all', we'll query the actual min/max from the data itself
+                // Set a reasonable default that will be overridden in the query
+                timeSeriesStart = "NOW() - INTERVAL '365 days'";
+                break;
+            default:
+                interval = 'hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 day'";
+                timeRangeInterval = '1 day';
+                timeSeriesStart = "NOW() - INTERVAL '1 day'";
+        }
+        if (timePeriod === 'custom-start' && customStartDate) {
+            timeFilter = `t.record_time >= '${customStartDate}:00' AND t.record_time < ('${customStartDate}:00'::timestamp + INTERVAL '${timeRangeInterval}')`;
+            timeSeriesStart = `'${customStartDate}:00'::timestamp`;
+            timeSeriesEnd = `('${customStartDate}:00'::timestamp + INTERVAL '${timeRangeInterval}')`;
+        }
+        const queryParams = [this.network];
+        let partyCondition = '';
+        if (partyFilter) {
+            queryParams.push(partyFilter);
+            // beneficiary can be in create_argument->>'beneficiary' or fallback to provider
+            partyCondition = ` AND (
+        c.create_argument->>'beneficiary' = $${queryParams.length}
+        OR (c.create_argument->>'beneficiary' IS NULL AND c.create_argument->>'provider' = $${queryParams.length})
+      )`;
+        }
+        // For couponStatus, we check if contract is archived (expired) or active (good)
+        // 'good' means not archived, 'expired' means archived
+        const statusCondition = couponStatus === 'expired'
+            ? ` AND EXISTS (
+        SELECT 1 FROM transaction_events e_archived
+        WHERE e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+      )`
+            : ` AND NOT EXISTS (
+        SELECT 1 FROM transaction_events e_archived
+        WHERE e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+      )`;
+        // For 'all' time range, we need to get the actual min/max from the data
+        const useDynamicRange = timeRange === 'all';
+        const query = useDynamicRange
+            ? `
+      WITH coupon_data AS (
+        SELECT
+          date_trunc('${interval}', t.record_time) AS timestamp,
+          COUNT(*) as count,
+          -- appRewardAmount is calculated from couponAmount * issuanceRate, but we don't have issuanceRate here
+          -- For now, we'll use 0 for amount (appRewardAmount) and only return couponAmount
+          -- TODO: Calculate appRewardAmount by joining with IssuingMiningRound contracts
+          COALESCE(SUM(0), 0) as amount,
+          COALESCE(SUM((c.create_argument->>'amount')::numeric), 0) as coupon_amount
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        WHERE t.network = $1
+          AND ${timeFilter}
+          AND e.kind = 'created'
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'AppRewardCoupon'
+          ${partyCondition}
+          ${statusCondition}
+        GROUP BY date_trunc('${interval}', t.record_time)
+      ),
+      time_bounds AS (
+        SELECT
+          COALESCE(MIN(timestamp), NOW() - INTERVAL '1 day') AS min_time,
+          COALESCE(MAX(timestamp), NOW()) AS max_time
+        FROM coupon_data
+      ),
+      time_series AS (
+        SELECT generate_series(
+          date_trunc('${interval}', (SELECT min_time FROM time_bounds)),
+          date_trunc('${interval}', (SELECT max_time FROM time_bounds)),
+          INTERVAL '1 ${interval}'
+        ) AS timestamp
+      )
+      SELECT
+        ts.timestamp::text,
+        COALESCE(cd.count, 0) as count,
+        COALESCE(cd.amount, 0) as amount,
+        COALESCE(cd.coupon_amount, 0) as coupon_amount
+      FROM time_series ts
+      LEFT JOIN coupon_data cd ON ts.timestamp = cd.timestamp
+      ORDER BY ts.timestamp ASC
+    `
+            : `
+      WITH time_series AS (
+        SELECT generate_series(
+          date_trunc('${interval}', ${timeSeriesStart}),
+          date_trunc('${interval}', ${timeSeriesEnd}),
+          INTERVAL '1 ${interval}'
+        ) AS timestamp
+      ),
+      coupon_data AS (
+        SELECT
+          date_trunc('${interval}', t.record_time) AS timestamp,
+          COUNT(*) as count,
+          -- appRewardAmount is calculated from couponAmount * issuanceRate, but we don't have issuanceRate here
+          -- For now, we'll use 0 for amount (appRewardAmount) and only return couponAmount
+          -- TODO: Calculate appRewardAmount by joining with IssuingMiningRound contracts
+          COALESCE(SUM(0), 0) as amount,
+          COALESCE(SUM((c.create_argument->>'amount')::numeric), 0) as coupon_amount
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        WHERE t.network = $1
+          AND ${timeFilter}
+          AND e.kind = 'created'
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'AppRewardCoupon'
+          ${partyCondition}
+          ${statusCondition}
+        GROUP BY date_trunc('${interval}', t.record_time)
+      )
+      SELECT
+        ts.timestamp::text,
+        COALESCE(cd.count, 0) as count,
+        COALESCE(cd.amount, 0) as amount,
+        COALESCE(cd.coupon_amount, 0) as coupon_amount
+      FROM time_series ts
+      LEFT JOIN coupon_data cd ON ts.timestamp = cd.timestamp
+      ORDER BY ts.timestamp ASC
+    `;
+        const result = await this.pool.query(query, queryParams);
+        return result.rows.map(row => ({
+            timestamp: row.timestamp,
+            count: parseInt(row.count, 10),
+            amount: parseFloat(row.amount),
+            couponAmount: parseFloat(row.coupon_amount),
+        }));
+    }
+    /**
+     * Get AppRewardCoupon round series data from Canton transactions
+     * Queries AppRewardCoupon created events and aggregates by round number
+     */
+    async getAppRewardCouponRoundSeriesData(timeRange, metric, timePeriod, customStartDate, partyFilter, couponStatus = 'good') {
+        let timeRangeInterval;
+        let timeFilter;
+        switch (timeRange) {
+            case '15m':
+                timeRangeInterval = '15 minutes';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '15 minutes'";
+                break;
+            case '1h':
+                timeRangeInterval = '1 hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 hour'";
+                break;
+            case '6h':
+                timeRangeInterval = '6 hours';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '6 hours'";
+                break;
+            case '1d':
+                timeRangeInterval = '1 day';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 day'";
+                break;
+            case '7d':
+                timeRangeInterval = '7 days';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '7 days'";
+                break;
+            case '30d':
+                timeRangeInterval = '30 days';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '30 days'";
+                break;
+            case 'last-month':
+                timeRangeInterval = '1 month';
+                timeFilter =
+                    "t.record_time >= date_trunc('month', current_date - interval '1 month') AND t.record_time < date_trunc('month', current_date)";
+                break;
+            case 'all':
+            default:
+                timeRangeInterval = '1 day';
+                timeFilter = 'TRUE';
+        }
+        if (timePeriod === 'custom-start' && customStartDate) {
+            timeFilter = `t.record_time >= '${customStartDate}:00' AND t.record_time < ('${customStartDate}:00'::timestamp + INTERVAL '${timeRangeInterval}')`;
+        }
+        const queryParams = [this.network];
+        let partyCondition = '';
+        if (partyFilter) {
+            queryParams.push(partyFilter);
+            // beneficiary can be in create_argument->>'beneficiary' or fallback to provider
+            partyCondition = ` AND (
+        c.create_argument->>'beneficiary' = $${queryParams.length}
+        OR (c.create_argument->>'beneficiary' IS NULL AND c.create_argument->>'provider' = $${queryParams.length})
+      )`;
+        }
+        // For couponStatus, we check if contract is archived (expired) or active (good)
+        const statusCondition = couponStatus === 'expired'
+            ? ` AND EXISTS (
+        SELECT 1 FROM transaction_events e_archived
+        WHERE e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+      )`
+            : ` AND NOT EXISTS (
+        SELECT 1 FROM transaction_events e_archived
+        WHERE e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+      )`;
+        const query = `
+      WITH time_filtered AS (
+        SELECT
+          (c.create_argument->'round'->>'number')::integer AS round_number
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        WHERE t.network = $1
+          AND ${timeFilter}
+          AND e.kind = 'created'
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'AppRewardCoupon'
+          ${partyCondition}
+          ${statusCondition}
+          AND (c.create_argument->'round'->>'number') IS NOT NULL
+      ),
+      round_bounds AS (
+        SELECT
+          COALESCE(MIN(round_number), 0) AS min_round,
+          COALESCE(MAX(round_number), 0) AS max_round
+        FROM time_filtered
+      ),
+      rounds AS (
+        SELECT generate_series(
+          GREATEST((SELECT min_round FROM round_bounds), 0),
+          GREATEST((SELECT max_round FROM round_bounds), 0)
+        ) AS round
+        WHERE (SELECT max_round FROM round_bounds) > 0
+      ),
+      coupon_data AS (
+        SELECT
+          (c.create_argument->'round'->>'number')::integer AS round,
+          MIN(t.record_time) AS timestamp,
+          COUNT(*) AS count,
+          -- appRewardAmount is calculated from couponAmount * issuanceRate, but we don't have issuanceRate here
+          -- For now, we'll use 0 for amount (appRewardAmount) and only return couponAmount
+          -- TODO: Calculate appRewardAmount by joining with IssuingMiningRound contracts
+          COALESCE(SUM(0), 0) AS amount,
+          COALESCE(SUM((c.create_argument->>'amount')::numeric), 0) AS coupon_amount
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        WHERE t.network = $1
+          AND ${timeFilter}
+          AND e.kind = 'created'
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'AppRewardCoupon'
+          ${partyCondition}
+          ${statusCondition}
+          AND (c.create_argument->'round'->>'number') IS NOT NULL
+        GROUP BY (c.create_argument->'round'->>'number')::integer
+      )
+      SELECT
+        r.round,
+        cd.timestamp,
+        COALESCE(cd.count, 0) AS count,
+        COALESCE(cd.amount, 0) AS amount,
+        COALESCE(cd.coupon_amount, 0) AS coupon_amount
+      FROM rounds r
+      LEFT JOIN coupon_data cd ON cd.round = r.round
+      ORDER BY r.round ASC
+    `;
+        const result = await this.pool.query(query, queryParams);
+        return result.rows.map(row => ({
+            timestamp: row.timestamp
+                ? new Date(row.timestamp).toISOString()
+                : new Date().toISOString(),
+            count: parseInt(row.count, 10),
+            amount: parseFloat(row.amount),
+            couponAmount: parseFloat(row.coupon_amount),
+            round: typeof row.round === 'number' ? row.round : parseInt(row.round, 10),
+        }));
+    }
+    /**
+     * Get AppMarker (FeaturedAppActivityMarker) time series data from Canton transactions
+     */
+    async getAppMarkerTimeSeriesData(timeRange, metric, timePeriod, customStartDate, partyFilter, status) {
+        let interval;
+        let timeFilter;
+        let timeSeriesStart;
+        let timeSeriesEnd = 'NOW()';
+        let timeRangeInterval;
+        switch (timeRange) {
+            case '15m':
+                interval = 'minute';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '15 minutes'";
+                timeRangeInterval = '15 minutes';
+                timeSeriesStart = "NOW() - INTERVAL '15 minutes'";
+                break;
+            case '1h':
+                interval = 'minute';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 hour'";
+                timeRangeInterval = '1 hour';
+                timeSeriesStart = "NOW() - INTERVAL '1 hour'";
+                break;
+            case '6h':
+                interval = 'minute';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '6 hours'";
+                timeRangeInterval = '6 hours';
+                timeSeriesStart = "NOW() - INTERVAL '6 hours'";
+                break;
+            case '1d':
+                interval = 'hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 day'";
+                timeRangeInterval = '1 day';
+                timeSeriesStart = "NOW() - INTERVAL '1 day'";
+                break;
+            case '7d':
+                interval = 'hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '7 days'";
+                timeRangeInterval = '7 days';
+                timeSeriesStart = "NOW() - INTERVAL '7 days'";
+                break;
+            case '30d':
+                interval = 'day';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '30 days'";
+                timeRangeInterval = '30 days';
+                timeSeriesStart = "NOW() - INTERVAL '30 days'";
+                break;
+            case 'last-month':
+                interval = 'day';
+                timeFilter =
+                    "t.record_time >= date_trunc('month', current_date - interval '1 month') AND t.record_time < date_trunc('month', current_date)";
+                timeRangeInterval = '1 month';
+                timeSeriesStart =
+                    "date_trunc('month', current_date - interval '1 month')";
+                timeSeriesEnd = "date_trunc('month', current_date)";
+                break;
+            case 'all':
+                interval = 'day';
+                timeFilter = 'TRUE';
+                timeRangeInterval = '100 years';
+                // For 'all', we'll query the actual min/max from the data itself
+                // Set a reasonable default that will be overridden in the query
+                timeSeriesStart = "NOW() - INTERVAL '365 days'";
+                break;
+            default:
+                interval = 'hour';
+                timeFilter = "t.record_time >= NOW() - INTERVAL '1 day'";
+                timeRangeInterval = '1 day';
+                timeSeriesStart = "NOW() - INTERVAL '1 day'";
+        }
+        if (timePeriod === 'custom-start' && customStartDate) {
+            timeFilter = `t.record_time >= '${customStartDate}:00' AND t.record_time < ('${customStartDate}:00'::timestamp + INTERVAL '${timeRangeInterval}')`;
+            timeSeriesStart = `'${customStartDate}:00'::timestamp`;
+            timeSeriesEnd = `('${customStartDate}:00'::timestamp + INTERVAL '${timeRangeInterval}')`;
+        }
+        const queryParams = [this.network];
+        let partyCondition = '';
+        if (partyFilter) {
+            queryParams.push(partyFilter);
+            // beneficiary can be in create_argument->>'beneficiary' or fallback to provider
+            partyCondition = ` AND (
+        c.create_argument->>'beneficiary' = $${queryParams.length}
+        OR (c.create_argument->>'beneficiary' IS NULL AND c.create_argument->>'provider' = $${queryParams.length})
+      )`;
+        }
+        let statusFilter = '';
+        if (status === 'created') {
+            statusFilter = ` AND NOT EXISTS (
+        SELECT 1 FROM transaction_events e_archived
+        WHERE e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+      )`;
+        }
+        else if (status === 'archived') {
+            statusFilter = ` AND EXISTS (
+        SELECT 1 FROM transaction_events e_archived
+        WHERE e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+      )`;
+        }
+        // For 'all' time range, we need to get the actual min/max from the data
+        const useDynamicRange = timeRange === 'all';
+        const query = useDynamicRange
+            ? `
+      WITH marker_data AS (
+        SELECT
+          date_trunc('${interval}', t.record_time) AS timestamp,
+          COUNT(*) FILTER (WHERE e.kind = 'created') as created_count,
+          COUNT(*) FILTER (WHERE e_archived.kind = 'archived') as archived_count,
+          COALESCE(SUM((c.create_argument->>'weight')::numeric) FILTER (WHERE e.kind = 'created'), 0) as created_weight,
+          COALESCE(SUM((c.create_argument->>'weight')::numeric) FILTER (WHERE e_archived.kind = 'archived'), 0) as archived_weight
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        LEFT JOIN transaction_events e_archived ON e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+        WHERE t.network = $1
+          AND ${timeFilter}
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'FeaturedAppActivityMarker'
+          ${partyCondition}
+          ${statusFilter}
+          AND (e.kind = 'created' OR e_archived.kind = 'archived')
+        GROUP BY date_trunc('${interval}', t.record_time)
+      ),
+      time_bounds AS (
+        SELECT
+          COALESCE(MIN(timestamp), NOW() - INTERVAL '1 day') AS min_time,
+          COALESCE(MAX(timestamp), NOW()) AS max_time
+        FROM marker_data
+      ),
+      time_series AS (
+        SELECT generate_series(
+          date_trunc('${interval}', (SELECT min_time FROM time_bounds)),
+          date_trunc('${interval}', (SELECT max_time FROM time_bounds)),
+          INTERVAL '1 ${interval}'
+        ) AS timestamp
+      )
+      SELECT
+        ts.timestamp::text,
+        COALESCE(md.created_count, 0) + COALESCE(md.archived_count, 0) as count,
+        COALESCE(md.created_count, 0) as created_count,
+        COALESCE(md.archived_count, 0) as archived_count,
+        COALESCE(md.created_weight, 0) as created_weight,
+        COALESCE(md.archived_weight, 0) as archived_weight
+      FROM time_series ts
+      LEFT JOIN marker_data md ON ts.timestamp = md.timestamp
+      ORDER BY ts.timestamp ASC
+    `
+            : `
+      WITH time_series AS (
+        SELECT generate_series(
+          date_trunc('${interval}', ${timeSeriesStart}),
+          date_trunc('${interval}', ${timeSeriesEnd}),
+          INTERVAL '1 ${interval}'
+        ) AS timestamp
+      ),
+      marker_data AS (
+        SELECT
+          date_trunc('${interval}', t.record_time) AS timestamp,
+          COUNT(*) FILTER (WHERE e.kind = 'created') as created_count,
+          COUNT(*) FILTER (WHERE e_archived.kind = 'archived') as archived_count,
+          COALESCE(SUM((c.create_argument->>'weight')::numeric) FILTER (WHERE e.kind = 'created'), 0) as created_weight,
+          COALESCE(SUM((c.create_argument->>'weight')::numeric) FILTER (WHERE e_archived.kind = 'archived'), 0) as archived_weight
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        LEFT JOIN transaction_events e_archived ON e_archived.contract_id = c.id AND e_archived.kind = 'archived'
+        WHERE t.network = $1
+          AND ${timeFilter}
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'FeaturedAppActivityMarker'
+          ${partyCondition}
+          ${statusFilter}
+          AND (e.kind = 'created' OR e_archived.kind = 'archived')
+        GROUP BY date_trunc('${interval}', t.record_time)
+      )
+      SELECT
+        ts.timestamp::text,
+        COALESCE(md.created_count, 0) + COALESCE(md.archived_count, 0) as count,
+        COALESCE(md.created_count, 0) as created_count,
+        COALESCE(md.archived_count, 0) as archived_count,
+        COALESCE(md.created_weight, 0) as created_weight,
+        COALESCE(md.archived_weight, 0) as archived_weight
+      FROM time_series ts
+      LEFT JOIN marker_data md ON ts.timestamp = md.timestamp
+      ORDER BY ts.timestamp ASC
+    `;
+        const result = await this.pool.query(query, queryParams);
+        return result.rows.map(row => ({
+            timestamp: row.timestamp,
+            count: parseInt(row.count, 10),
+            createdCount: row.created_count
+                ? parseInt(row.created_count, 10)
+                : undefined,
+            archivedCount: row.archived_count
+                ? parseInt(row.archived_count, 10)
+                : undefined,
+            createdWeight: row.created_weight
+                ? parseFloat(row.created_weight)
+                : undefined,
+            archivedWeight: row.archived_weight
+                ? parseFloat(row.archived_weight)
+                : undefined,
+        }));
+    }
+    /**
+     * Get unique beneficiary parties from AppRewardCoupon contracts
+     */
+    async getUniqueCouponBeneficiaryParties() {
+        const query = `
+      SELECT DISTINCT
+        COALESCE(c.create_argument->>'beneficiary', c.create_argument->>'provider') AS party_id,
+        COALESCE(c.create_argument->>'beneficiary', c.create_argument->>'provider') AS display_name
+      FROM transactions t
+      JOIN transaction_events e ON e.transaction_id = t.id
+      JOIN contracts c ON c.id = e.contract_id
+      JOIN templates tmpl ON c.template_id = tmpl.id
+      WHERE t.network = $1
+        AND e.kind = 'created'
+        AND tmpl.package_name = 'splice-amulet'
+        AND tmpl.module_name = 'Splice.Amulet'
+        AND tmpl.template_name = 'AppRewardCoupon'
+        AND (c.create_argument->>'beneficiary' IS NOT NULL OR c.create_argument->>'provider' IS NOT NULL)
+      ORDER BY party_id
+    `;
+        const result = await this.pool.query(query, [this.network]);
+        return result.rows.map(row => ({
+            party_id: row.party_id,
+            display_name: row.display_name || row.party_id,
+        }));
+    }
+    /**
+     * Get unique beneficiary parties from FeaturedAppActivityMarker contracts
+     */
+    async getUniqueMarkerBeneficiaryParties() {
+        const query = `
+      SELECT DISTINCT
+        COALESCE(c.create_argument->>'beneficiary', c.create_argument->>'provider') AS party_id,
+        COALESCE(c.create_argument->>'beneficiary', c.create_argument->>'provider') AS display_name
+      FROM transactions t
+      JOIN transaction_events e ON e.transaction_id = t.id
+      JOIN contracts c ON c.id = e.contract_id
+      JOIN templates tmpl ON c.template_id = tmpl.id
+      WHERE t.network = $1
+        AND e.kind = 'created'
+        AND tmpl.package_name = 'splice-amulet'
+        AND tmpl.module_name = 'Splice.Amulet'
+        AND tmpl.template_name = 'FeaturedAppActivityMarker'
+        AND (c.create_argument->>'beneficiary' IS NOT NULL OR c.create_argument->>'provider' IS NOT NULL)
+      ORDER BY party_id
+    `;
+        const result = await this.pool.query(query, [this.network]);
+        return result.rows.map(row => ({
+            party_id: row.party_id,
+            display_name: row.display_name || row.party_id,
+        }));
+    }
+    /**
+     * Get last AppRewardCoupon timestamp
+     */
+    async getLastAppRewardCouponTimestamp(partyFilter) {
+        const queryParams = [this.network];
+        let partyCondition = '';
+        if (partyFilter) {
+            queryParams.push(partyFilter);
+            // beneficiary can be in create_argument->>'beneficiary' or fallback to provider
+            partyCondition = ` AND (
+        c.create_argument->>'beneficiary' = $${queryParams.length}
+        OR (c.create_argument->>'beneficiary' IS NULL AND c.create_argument->>'provider' = $${queryParams.length})
+      )`;
+        }
+        const query = `
+      SELECT MAX(t.record_time) AS last_timestamp
+      FROM transactions t
+      JOIN transaction_events e ON e.transaction_id = t.id
+      JOIN contracts c ON c.id = e.contract_id
+      JOIN templates tmpl ON c.template_id = tmpl.id
+      WHERE t.network = $1
+        AND e.kind = 'created'
+        AND tmpl.package_name = 'splice-amulet'
+        AND tmpl.module_name = 'Splice.Amulet'
+        AND tmpl.template_name = 'AppRewardCoupon'
+        ${partyCondition}
+    `;
+        const result = await this.pool.query(query, queryParams);
+        if (result.rows.length === 0 || !result.rows[0].last_timestamp) {
+            return null;
+        }
+        return new Date(result.rows[0].last_timestamp).toISOString();
+    }
+    /**
+     * Get lifetime app rewards (sum of all AppRewardCoupon amounts)
+     */
+    async getLifetimeAppRewards() {
+        const query = `
+      -- appRewardAmount is calculated, not stored in contract
+      -- For now return 0, TODO: Calculate by joining with IssuingMiningRound
+      SELECT COALESCE(SUM(0), 0) AS total_rewards
+      FROM transactions t
+      JOIN transaction_events e ON e.transaction_id = t.id
+      JOIN contracts c ON c.id = e.contract_id
+      JOIN templates tmpl ON c.template_id = tmpl.id
+      WHERE t.network = $1
+        AND e.kind = 'created'
+        AND tmpl.package_name = 'splice-amulet'
+        AND tmpl.module_name = 'Splice.Amulet'
+        AND tmpl.template_name = 'AppRewardCoupon'
+    `;
+        const result = await this.pool.query(query, [this.network]);
+        return parseFloat(result.rows[0]?.total_rewards ?? '0');
+    }
+    /**
+     * Get latest coupon amounts (featured and unfeatured)
+     */
+    async getLatestCouponAmounts() {
+        const query = `
+      WITH latest_coupons AS (
+        SELECT DISTINCT ON (
+          CASE WHEN (c.create_argument->>'featured')::boolean THEN 'featured' ELSE 'unfeatured' END
+        )
+          (c.create_argument->>'featured')::boolean AS featured,
+          (c.create_argument->>'amount')::numeric AS coupon_amount,
+          t.record_time
+        FROM transactions t
+        JOIN transaction_events e ON e.transaction_id = t.id
+        JOIN contracts c ON c.id = e.contract_id
+        JOIN templates tmpl ON c.template_id = tmpl.id
+        WHERE t.network = $1
+          AND e.kind = 'created'
+          AND tmpl.package_name = 'splice-amulet'
+          AND tmpl.module_name = 'Splice.Amulet'
+          AND tmpl.template_name = 'AppRewardCoupon'
+          AND c.create_argument->>'amount' IS NOT NULL
+        ORDER BY
+          CASE WHEN (c.create_argument->>'featured')::boolean THEN 'featured' ELSE 'unfeatured' END,
+          t.record_time DESC
+      )
+      SELECT
+        MAX(coupon_amount) FILTER (WHERE featured = true) AS featured_amount,
+        MAX(coupon_amount) FILTER (WHERE featured = false OR featured IS NULL) AS unfeatured_amount
+      FROM latest_coupons
+    `;
+        const result = await this.pool.query(query, [this.network]);
+        const row = result.rows[0] ?? {};
+        return {
+            featured: row.featured_amount !== null && row.featured_amount !== undefined
+                ? parseFloat(row.featured_amount)
+                : null,
+            unfeatured: row.unfeatured_amount !== null && row.unfeatured_amount !== undefined
+                ? parseFloat(row.unfeatured_amount)
+                : null,
+        };
+    }
+    /**
+     * Get active contracts with optional filtering.
+     * Mirrors the SDK's getActiveContracts but runs against the local database.
+     * Note: For performance, signatories/observers/witnessParties are not included.
+     */
+    async getActiveContracts(options) {
+        const { partyId, templateIds } = options;
+        const queryParams = [this.network];
+        const conditions = ['c.network = $1'];
+        // 1. Filter by Party (readAs)
+        if (partyId) {
+            queryParams.push(partyId);
+            conditions.push(`
+        EXISTS (
+          SELECT 1 FROM contract_actors ca
+          INNER JOIN parties p ON ca.party_id = p.id
+          WHERE ca.contract_id = c.id
+            AND p.party_id = $${queryParams.length}
+        )
+      `);
+        }
+        // 2. Filter by Template IDs
+        if (templateIds && templateIds.length > 0) {
+            queryParams.push(templateIds);
+            conditions.push(`
+        (pkg.package_id || ':' || tmpl.module_name || ':' || tmpl.template_name) = ANY($${queryParams.length})
+      `);
+        }
+        const query = `
+      SELECT
+        c.canton_contract_id AS contract_id,
+        t.record_time,
+        (pkg.package_id || ':' || tmpl.module_name || ':' || tmpl.template_name) AS template_id,
+        tmpl.package_name,
+        c.create_argument
+      FROM contracts c
+      INNER JOIN active_contracts ac ON ac.contract_id = c.id
+      INNER JOIN transaction_events e ON e.contract_id = c.id AND e.kind = 'created'
+      INNER JOIN transactions t ON t.id = e.transaction_id
+      INNER JOIN templates tmpl ON tmpl.id = c.template_id
+      INNER JOIN packages pkg ON pkg.id = e.package_id
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY t.record_time DESC
+    `;
+        try {
+            const result = await this.pool.query(query, queryParams);
+            return result.rows.map(row => {
+                const createArgument = typeof row.create_argument === 'string'
+                    ? JSON.parse(row.create_argument)
+                    : row.create_argument;
+                return {
+                    contractEntry: {
+                        JsActiveContract: {
+                            createdEvent: {
+                                contractId: row.contract_id,
+                                templateId: row.template_id,
+                                createArgument: (createArgument || {}),
+                                createdAt: row.record_time
+                                    ? new Date(row.record_time).toISOString()
+                                    : new Date().toISOString(),
+                                packageName: row.package_name,
+                            },
+                            synchronizerId: 'unknown',
+                            reassignmentCounter: '0',
+                        },
+                    },
+                };
+            });
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+}
+exports.CantonDbClient = CantonDbClient;
+//# sourceMappingURL=cantonDbClient.js.map