additional helpful logs

CONTRIBUTING.md

@@ -18,6 +18,21 @@ npm install
 
 The Validator History Service only supports Postgres. You'll need to create a database, but the Validator History Service will create the schema for you.
 
+Here are some helpful commands to set up the Postgres SQL data base on MacOS.
+```
+brew install postgresql # installs utility tools to interact with the data base
+```
+
+If you would like to only view/inspect some records of an existing database, you can install the essential tools with `brew install psql` (You need to add the binary file to the PATH variable)
+
+Homebrew sets the machine username as the super user of the Postgres data base. You can find your user name through `whoami` command on the terminal.
+```
+psql -U <username> -c '\l' # lists all the databases managed by psql
+psql -U <username> -c 'create database <data_base_name>;' # This step is required by the VHS. The database_name must match the environment variable in .env file
+```
+
+These step should suffice to run VHS on your local machine.
+
 ## Linting and testing
 
 ### Linting

src/connection-manager/chains.ts

@@ -62,7 +62,7 @@
   try {
     await Promise.all(promises)
   } catch (err: unknown) {
-    log.error('Error saving validator chains', err)
+    log.error(`Error saving chain data into validators table: ${err}`)
   }
 }
 
@@ -131,6 +131,7 @@
    * Clears all ledgers seen on a chain and saves the chain for each validator.
    */
   public async purgeChains(): Promise<void> {
+    log.info('Purging chains...')
     const promises: Array<Promise<void>> = []
 
     this.chains = this.chains.filter((chain) => {
@@ -154,6 +155,7 @@
   private getNextChainID(): string {
     if (this.index > 10000) {
       this.index = 0
+      log.error('Chain index overflowed at 10,000. Rounding back to 0.')
     }
 
     const id = `chain.${this.index}`
@@ -215,6 +217,8 @@
       .sort(sortChainLength)
       .shift()
 
+    // `ledger` has already been processed and added into the `chainAtThisIndex`.
+    // TODO: Add an additional check on the ledger_hash parameter to ensure that VHS is not processing conflicting ledgers.
     if (chainAtThisIndex !== undefined) {
       return
     }
@@ -228,8 +232,11 @@
     )
 
     if (chainWithThisValidator !== undefined) {
+      // compute the difference between the most recent ledger versus the stored ledger in `chainWithThisValidator`.
       const skipped = ledger.ledger_index - chainWithThisValidator.current
-      log.warn(`Possibly skipped ${skipped} ledgers`)
+      log.warn(
+        `Skipped ${skipped} ledgers in chain: ${chainWithThisValidator.id}. Processing incoming ledger with hash: ${ledger.ledger_hash} into the said chain.`,
+      )
       if (skipped > 1 && skipped < 20) {
         chainWithThisValidator.incomplete = true
         addLedgerToChain(ledger, chainWithThisValidator)

src/connection-manager/connections.ts

@@ -58,7 +58,11 @@
 ): Promise<void> {
   const ledger_hashes: string[] = []
   return new Promise(function setHandlersPromise(resolve, _reject) {
-    ws.on('open', () => {
+    ws.on('open', (err: unknown) => {
+      if (err) {
+        log.error(`Error upon opening websocket: ${err}`)
+        return
+      }
       if (connections.has(ip)) {
         resolve()
         return
@@ -85,6 +89,7 @@
         log.error('Error parsing validation message', error)
         return
       }
+      log.info(`Received message on websocket: ${data}`)
 
       if (data.result?.node) {
         void handleWsMessageLedgerEntryAmendments(
@@ -108,14 +113,15 @@
     })
     ws.on('close', async (code, reason) => {
       const nodeNetworks = networks ?? 'unknown network'
+      log.error(
+        `Websocket closed for ${
+          ws.url
+        } on ${nodeNetworks} with code ${code} and reason ${reason.toString(
+          'utf-8',
+        )}.`,
+      )
+
       if (connectionsInitialized) {
-        log.error(
-          `Websocket closed for ${
-            ws.url
-          } on ${nodeNetworks} with code ${code} and reason ${reason.toString(
-            'utf-8',
-          )}.`,
-        )
         if (CLOSING_CODES.includes(code)) {
           log.info(
             `Reconnecting to ${ws.url} on ${networks ?? 'unknown network'}...`,
@@ -139,7 +145,10 @@
       ws.terminate()
       resolve()
     })
-    ws.on('error', () => {
+    ws.on('error', (err) => {
+      if (err) {
+        log.error(`Error on websocket: ${err}`)
+      }
       if (connections.get(ip)?.url === ws.url) {
         connections.delete(ip)
       }

src/connection-manager/wsHandling.ts

@@ -51,6 +51,9 @@ export function subscribe(ws: WebSocket): void {
       streams: ['manifests', 'validations', 'ledger'],
     }),
   )
+  log.info(
+    `Subscribed to manifests, validations, and ledger streams on this websocket endpoint: ${ws.url}`,
+  )
 }
 
 /**

src/crawler/crawl.ts

@@ -189,7 +189,7 @@
    * @param unls - List of UNLs on the current network.
    * @returns Void.
    */
   private async crawlEndpoint(
     host: string,
     port: number,
     unls: string[],
@@ -213,6 +213,9 @@
           node.complete_ledgers,
         )
       ) {
+        log.info(
+          `Node ${normalizedPublicKey} does not have relevant complete ledgers`,
+        )
         continue
       }
 
@@ -229,6 +232,9 @@
       }
 
       if (this.publicKeysSeen.has(normalizedPublicKey)) {
+        log.info(
+          `Node ${normalizedPublicKey} has already been processed for crawl process`,
+        )
         continue
       }
 

src/crawler/network.ts

@@ -32,7 +32,9 @@
 const TIMEOUT = 6000
 
 /**
  * Crawl endpoint at host:port/crawl.
+ * Refer to the peer_crawler API docs for more information:
+ * https://xrpl.org/docs/references/http-websocket-apis/peer-port-methods/peer-crawler#response-format
  *
  * @param host - Hostname or ip address of peer.
  * @param port - Port to hit /crawl endpoint.