@odatano/nightgate 0.1.0 → 0.1.1

package/srv/nightgate-service.cds

@@ -1,4 +1,4 @@
-using { midnight } from '../db/schema';
+using {midnight} from '../db/schema';
 
 /**
  * Nightgate Blockchain OData V4 API Service
@@ -6,7 +6,7 @@ using { midnight } from '../db/schema';
  * This service exposes Midnight blockchain data as a Nightgate OData V4 API,
  * following enterprise architecture patterns.
  */
-@path: '/api/v1/nightgate'
+@path    : '/api/v1/nightgate'
 @requires: 'authenticated-user'
 service NightgateService {
 
@@ -14,193 +14,215 @@ service NightgateService {
     // Blockchain Core - Read-Only Access
     // ========================================================================
 
-    /**
-     * Blocks endpoint with full navigation capabilities
-     * Supports: $filter, $orderby, $expand, $select, $top, $skip
-     */
+            /**
+             * Blocks endpoint with full navigation capabilities
+             * Supports: $filter, $orderby, $expand, $select, $top, $skip
+             */
     @readonly
-    entity Blocks as projection on midnight.Blocks {
-        *,
-        parent,
-        transactions,
-        systemParameters
-    } actions {
-        // Get latest block
-        @cds.odata.bindingparameter.collection
-        function latest() returns Blocks;
-
-        // Get block by height
-        function byHeight(height: Integer) returns Blocks;
-    };
-
-    /**
-     * Transactions with expanded relationships
-     */
+    entity Blocks                    as
+        projection on midnight.Blocks {
+            *,
+            parent,
+            transactions,
+            systemParameters
+        }
+        actions {
+            // Get latest block
+            @cds.odata.bindingparameter.collection
+            function latest()                                                            returns Blocks;
+
+            // Get block by height
+            function byHeight(height: Integer)                                           returns Blocks;
+
+            // Windowed range query for block pagination
+            @cds.odata.bindingparameter.collection
+            function range(startHeight: Integer64, endHeight: Integer64, limit: Integer) returns array of Blocks;
+        };
+
+            /**
+             * Transactions with expanded relationships
+             */
     @readonly
-    entity Transactions as projection on midnight.Transactions {
-        *,
-        block,
-        transactionResult,
-        transactionFees,
-        contractActions,
-        unshieldedCreatedOutputs,
-        unshieldedSpentOutputs,
-        zswapLedgerEvents,
-        dustLedgerEvents
-    } actions {
-        // Get transaction by hash
-        function byHash(hash: String) returns Transactions;
-    };
+    entity Transactions              as
+        projection on midnight.Transactions {
+            *,
+            block,
+            transactionResult,
+            transactionFees,
+            contractActions,
+            unshieldedCreatedOutputs,
+            unshieldedSpentOutputs,
+            zswapLedgerEvents,
+            dustLedgerEvents
+        }
+        actions {
+            // Get transaction by hash
+            function byHash(hash: String)                   returns Transactions;
+
+            // Filter transactions by classified tx type
+            @cds.odata.bindingparameter.collection
+            function byType(txType: String, limit: Integer) returns array of Transactions;
+        };
 
     @readonly
-    entity TransactionResults as projection on midnight.TransactionResults;
+    entity TransactionResults        as projection on midnight.TransactionResults;
 
     @readonly
-    entity TransactionSegments as projection on midnight.TransactionSegments;
+    entity TransactionSegments       as projection on midnight.TransactionSegments;
 
     @readonly
-    entity TransactionFees as projection on midnight.TransactionFees;
+    entity TransactionFees           as projection on midnight.TransactionFees;
 
     // ========================================================================
     // Smart Contracts
     // ========================================================================
 
-    /**
-     * Contract actions with deployment, call, and update tracking
-     */
+            /**
+             * Contract actions with deployment, call, and update tracking
+             */
     @readonly
-    entity ContractActions as projection on midnight.ContractActions {
-        *,
-        transaction,
-        deploy,
-        unshieldedBalances
-    } actions {
-        // Get contract actions by address
-        @cds.odata.bindingparameter.collection
-        function byAddress(address: String) returns array of ContractActions;
-
-        // Get contract history
-        function history(address: String) returns array of ContractActions;
-    };
+    entity ContractActions           as
+        projection on midnight.ContractActions {
+            *,
+            transaction,
+            deploy,
+            unshieldedBalances
+        }
+        actions {
+            // Get contract actions by address
+            @cds.odata.bindingparameter.collection
+            function byAddress(address: String) returns array of ContractActions;
+
+            // Get contract history
+            function history(address: String)   returns array of ContractActions;
+        };
 
     @readonly
-    entity ContractBalances as projection on midnight.ContractBalances;
+    entity ContractBalances          as projection on midnight.ContractBalances;
 
     // ========================================================================
     // UTXOs
     // ========================================================================
 
-    /**
-     * Unshielded UTXOs for transparent transactions
-     */
+            /**
+             * Unshielded UTXOs for transparent transactions
+             */
     @readonly
-    entity UnshieldedUtxos as projection on midnight.UnshieldedUtxos {
-        *,
-        createdAtTransaction,
-        spentAtTransaction
-    } actions {
-        // Get UTXOs by owner
-        @cds.odata.bindingparameter.collection
-        function byOwner(owner: String) returns array of UnshieldedUtxos;
-
-        // Get unspent UTXOs
-        @cds.odata.bindingparameter.collection
-        function unspent() returns array of UnshieldedUtxos;
-    };
+    entity UnshieldedUtxos           as
+        projection on midnight.UnshieldedUtxos {
+            *,
+            createdAtTransaction,
+            spentAtTransaction
+        }
+        actions {
+            // Get UTXOs by owner
+            @cds.odata.bindingparameter.collection
+            function byOwner(owner: String) returns array of UnshieldedUtxos;
+
+            // Get unspent UTXOs
+            @cds.odata.bindingparameter.collection
+            function unspent()              returns array of UnshieldedUtxos;
+        };
 
     // ========================================================================
     // Ledger Events
     // ========================================================================
 
     @readonly
-    entity ZswapLedgerEvents as projection on midnight.ZswapLedgerEvents;
+    entity ZswapLedgerEvents         as projection on midnight.ZswapLedgerEvents;
 
     @readonly
-    entity DustLedgerEvents as projection on midnight.DustLedgerEvents;
+    entity DustLedgerEvents          as projection on midnight.DustLedgerEvents;
 
     // ========================================================================
     // Governance & System Parameters
     // ========================================================================
 
-    /**
-     * Current system parameters
-     */
+            /**
+             * Current system parameters
+             */
     @readonly
-    entity SystemParameters as projection on midnight.SystemParameters actions {
-        // Get current active parameters
-        @cds.odata.bindingparameter.collection
-        function current() returns SystemParameters;
-    };
+    entity SystemParameters          as projection on midnight.SystemParameters
+        actions {
+            // Get current active parameters
+            @cds.odata.bindingparameter.collection
+            function current() returns SystemParameters;
+        };
 
     /**
      * D-Parameter change history for governance tracking
      */
     @readonly
-    entity DParameterHistory as projection on midnight.DParameterHistory {
-        *,
-        block
-    };
+    entity DParameterHistory         as
+        projection on midnight.DParameterHistory {
+            *,
+            block
+        };
 
     /**
      * Terms and Conditions history
      */
     @readonly
-    entity TermsAndConditionsHistory as projection on midnight.TermsAndConditionsHistory {
-        *,
-        block
-    };
+    entity TermsAndConditionsHistory as
+        projection on midnight.TermsAndConditionsHistory {
+            *,
+            block
+        };
 
     // ========================================================================
     // DUST Generation
     // ========================================================================
 
-    /**
-     * DUST generation status for Cardano staking rewards
-     */
+            /**
+             * DUST generation status for Cardano staking rewards
+             */
     @readonly
-    entity DustGenerationStatus as projection on midnight.DustGenerationStatus actions {
-        // Query by Cardano reward address
-        @cds.odata.bindingparameter.collection
-        function byCardanoAddress(address: String) returns DustGenerationStatus;
+    entity DustGenerationStatus      as projection on midnight.DustGenerationStatus
+        actions {
+            // Query by Cardano reward address
+            @cds.odata.bindingparameter.collection
+            function byCardanoAddress(address: String)              returns DustGenerationStatus;
 
-        // Batch query for multiple addresses
-        @cds.odata.bindingparameter.collection
-        function byCardanoAddresses(addresses: array of String) returns array of DustGenerationStatus;
-    };
+            // Batch query for multiple addresses
+            @cds.odata.bindingparameter.collection
+            function byCardanoAddresses(addresses: array of String) returns array of DustGenerationStatus;
+        };
 
     // ========================================================================
     // Balance & Token Tracking
     // ========================================================================
 
-    /**
-     * Unshielded NIGHT token balances per address
-     */
+            /**
+             * Unshielded NIGHT token balances per address
+             */
     @readonly
-    entity NightBalances as projection on midnight.NightBalances actions {
-        // Get balance for a specific address
-        @cds.odata.bindingparameter.collection
-        function getBalance(address: String) returns NightBalances;
-
-        // Get top holders by balance
-        @cds.odata.bindingparameter.collection
-        function getTopHolders(limit: Integer) returns array of NightBalances;
-    };
-
-    /**
-     * NIGHT ↔ DUST registration linkage
-     */
+    entity NightBalances             as projection on midnight.NightBalances
+        actions {
+            // Get balance for a specific address
+            @cds.odata.bindingparameter.collection
+            function getBalance(address: String)   returns NightBalances;
+
+            // Get top holders by balance
+            @cds.odata.bindingparameter.collection
+            function getTopHolders(limit: Integer) returns array of NightBalances;
+        };
+
+            /**
+             * NIGHT ↔ DUST registration linkage
+             */
     @readonly
-    entity DustRegistrations as projection on midnight.DustRegistrations actions {
-        // Get registration by Cardano stake key
-        @cds.odata.bindingparameter.collection
-        function byCardanoStakeKey(stakeKey: String) returns DustRegistrations;
-    };
+    entity DustRegistrations         as projection on midnight.DustRegistrations
+        actions {
+            // Get registration by Cardano stake key
+            @cds.odata.bindingparameter.collection
+            function byCardanoStakeKey(stakeKey: String) returns DustRegistrations;
+        };
 
     /**
      * Token type registry
      */
     @readonly
-    entity TokenTypes as projection on midnight.TokenTypes;
+    entity TokenTypes                as projection on midnight.TokenTypes;
 
     // ========================================================================
     // Session Management (Wallet Connections)
@@ -209,14 +231,50 @@ service NightgateService {
     /**
      * Wallet session management
      */
-    entity WalletSessions as projection on midnight.WalletSessions excluding {
-        viewingKeyHash,         // Internal lookup field
-        encryptedViewingKey     // Encrypted key — never exposed via OData
-    } actions {
-        // Connect with viewing key
-        action connectWallet(viewingKey: String) returns WalletSessions;
-
-        // Disconnect session
-        action disconnectWallet(sessionId: UUID);
-    };
+    entity WalletSessions            as
+        projection on midnight.WalletSessions
+        excluding {
+            viewingKeyHash, // Internal lookup field
+            encryptedViewingKey // Encrypted key — never exposed via OData
+        }
+        actions {
+            // Connect with viewing key
+            action connectWallet(viewingKey: String) returns WalletSessions;
+
+            // Disconnect session
+            action disconnectWallet(sessionId: UUID);
+        };
 }
+
+// ============================================================================
+// Service-Level Annotations
+// ============================================================================
+
+annotate NightgateService.Blocks with {
+    hash   @title: 'Block Hash';
+    height @title: 'Block Height';
+};
+
+annotate NightgateService.Transactions with {
+    hash @title: 'Transaction Hash';
+};
+
+annotate NightgateService.ContractActions with {
+    address @title: 'Contract Address';
+};
+
+annotate NightgateService.DustGenerationStatus with {
+    cardanoRewardAddress @title: 'Cardano Reward Address';
+    nightBalance         @title: 'NIGHT Balance';
+    generationRate       @title: 'Generation Rate';
+};
+
+annotate NightgateService.NightBalances with {
+    address @title: 'Address';
+    balance @title: 'NIGHT Balance';
+};
+
+annotate NightgateService.TokenTypes with {
+    tokenTypeId @title: 'Token Type ID';
+    tokenName   @title: 'Token Name';
+};

package/srv/nightgate-service.js

@@ -35,6 +35,23 @@ class NightgateService extends cds_1.default.ApplicationService {
                 return req.reject(400, 'height is required');
             return this.db.run(cds_1.default.ql.SELECT.one.from('midnight.Blocks').where({ height }));
         });
+        this.on('range', 'Blocks', async (req) => {
+            const { startHeight, endHeight, limit } = req.data;
+            if (startHeight == null || endHeight == null) {
+                return req.reject(400, 'startHeight and endHeight are required');
+            }
+            if (!Number.isInteger(startHeight) || !Number.isInteger(endHeight) || startHeight < 0 || endHeight < 0) {
+                return req.reject(400, 'startHeight and endHeight must be non-negative integers');
+            }
+            if (endHeight < startHeight) {
+                return req.reject(400, 'endHeight must be greater than or equal to startHeight');
+            }
+            const effectiveLimit = Math.min(Math.max(limit || 100, 1), 5000);
+            return this.db.run(cds_1.default.ql.SELECT.from('midnight.Blocks')
+                .where({ height: { '>=': startHeight, '<=': endHeight } })
+                .orderBy('height asc')
+                .limit(effectiveLimit));
+        });
         // ====================================================================
         // Transaction Handlers
         // ====================================================================
@@ -47,6 +64,16 @@ class NightgateService extends cds_1.default.ApplicationService {
                 return req.reject(400, 'hash is required');
             return this.db.run(cds_1.default.ql.SELECT.from('midnight.Transactions').where({ hash }));
         });
+        this.on('byType', 'Transactions', async (req) => {
+            const { txType, limit } = req.data;
+            if (!txType)
+                return req.reject(400, 'txType is required');
+            const effectiveLimit = Math.min(Math.max(limit || 100, 1), 2000);
+            return this.db.run(cds_1.default.ql.SELECT.from('midnight.Transactions')
+                .where({ txType })
+                .orderBy('createdAt desc')
+                .limit(effectiveLimit));
+        });
         // ====================================================================
         // Contract Handlers
         // ====================================================================

package/srv/providers/MidnightNodeProvider.js

@@ -175,7 +175,19 @@ class MidnightNodeProvider {
         if (message.method && message.params?.subscription) {
             const callback = this.subscriptions.get(message.params.subscription);
             if (callback) {
-                callback(message.params.result);
+                try {
+                    const callbackResult = callback(message.params.result);
+                    if (callbackResult && typeof callbackResult.then === 'function') {
+                        void callbackResult.catch((err) => {
+                            const errMsg = err instanceof Error ? err.message : String(err);
+                            console.error('[MidnightNode] Subscription callback failed:', errMsg);
+                        });
+                    }
+                }
+                catch (err) {
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    console.error('[MidnightNode] Subscription callback failed:', errMsg);
+                }
             }
             return;
         }

package/srv/utils/scale.d.ts

@@ -1,40 +1,41 @@
 /**
  * Minimal SCALE codec helpers for Substrate extrinsic parsing.
  *
- * Only implements what's needed to extract pallet_index + call_index
- * from hex-encoded extrinsics. No external dependencies.
+ * Includes:
+ * - compact integer decoding
+ * - pallet/call extraction
+ * - signed participant extraction (sender/receiver/amount for transfer-like calls)
  */
+export interface ExtrinsicParticipantInfo {
+    isSigned: boolean;
+    palletIndex: number;
+    callIndex: number;
+    senderAddress?: string;
+    receiverAddress?: string;
+    amount?: string;
+}
 /**
- * Decode a SCALE compact-encoded unsigned integer.
+ * Decode a SCALE compact-encoded unsigned integer as bigint.
  * Returns [value, bytesConsumed] or null if buffer too short.
- *
- * Compact encoding modes (2 LSBs of first byte):
- *   0b00 → single-byte mode:  value = byte >> 2          (0..63)
- *   0b01 → two-byte mode:     value = u16 >> 2           (64..16383)
- *   0b10 → four-byte mode:    value = u32 >> 2           (16384..2^30-1)
- *   0b11 → big-integer mode:  upper 6 bits = extra bytes (not supported here)
+ */
+export declare function decodeCompactBigInt(buf: Buffer, offset: number): [bigint, number] | null;
+/**
+ * Compatibility wrapper for existing callers that expect number values.
+ * Values above Number.MAX_SAFE_INTEGER are returned as 0 while preserving bytesConsumed.
  */
 export declare function decodeCompact(buf: Buffer, offset: number): [number, number] | null;
 /**
  * Parse a hex-encoded Substrate extrinsic to extract pallet_index and call_index.
- *
- * Extrinsic structure:
- *   [compact_length][version_byte][...payload...]
- *
- * Version byte:
- *   bit 7 = signed flag (0x84 = signed v4, 0x04 = unsigned v4)
- *
- * Unsigned payload:
- *   [pallet_index: u8][call_index: u8][args...]
- *
- * Signed payload:
- *   [address_type: u8][account_id: 32B][sig_type: u8][signature: 64B]
- *   [era: 1-2B][nonce: compact][tip: compact]
- *   [pallet_index: u8][call_index: u8][args...]
- *
  * Returns null on parse failure (safe fallback to existing heuristics).
  */
 export declare function parseExtrinsicCallIndices(hex: string): {
     palletIndex: number;
     callIndex: number;
 } | null;
+/**
+ * Extract signed sender + first transfer-style destination/amount, if present.
+ *
+ * This parser is intentionally conservative: receiver/amount are set only when
+ * the first call args decode as MultiAddress + Compact<Balance>.
+ */
+export declare function parseExtrinsicParticipantInfo(hex: string): ExtrinsicParticipantInfo | null;